Autenticación y Seguridad
La Integration API usa JWT Bearer tokens de corta duración. Se obtienen
cambiando la apiKey y el secret
de tu organización —los emite su owner, ver Getting Started—
por un token de 10 minutos.
accessToken
solo en memoria (nunca en localStorage ni cookies).
El renewToken puede
persistirse en sessionStorage
para sobrevivir recargas de página.
1. Login — obtén tus tokens
Envía la apiKey y el secret de tu
organización; la ruta es abierta, sin Bearer. La respuesta contiene un
accessToken (JWT, scope=integration, 10 minutos)
y un renewToken (7 días). Cualquier fallo de credenciales da el
mismo 401, y a partir de 10 intentos por minuto, 429.
La respuesta viene siempre envuelta en { "data": {...}, "requestId": "hex32" }.
Lee los tokens desde response.data.accessToken y response.data.renewToken.
2. Cabecera de autorización
Pasa el accessToken como
Authorization header en todas las peticiones protegidas.
| Header | Valor | Requerido |
|---|---|---|
| Authorization | Bearer <accessToken> | Sí |
| Content-Type | application/json | En POST/PATCH/PUT |
3. Renovar antes de que expire
El accessToken dura 10 minutos.
Decodifica el claim exp del JWT
y programa la renovación ~2 minutos antes. El renewToken
rota en cada renovación: el anterior deja de servir, así que guarda siempre el nuevo.
401 en cualquier endpoint protegido
significa que el accessToken expiró. Renueva y reintenta la petición original
una sola vez. Un 403 {"error":"forbidden scope"}
es otra cosa: el token de integración sólo sirve en /integration/v1/* y
/integration/webhook*.