La API de plataforma usa JSON Web Tokens (JWT) para la autenticación de operadores. Esta es la credencial que la consola usa en nombre de un operador conectado, y la misma credencial que tú usas al llamar a la API desde tus propios scripts o integraciones.
No es la misma credencial que usan los agentes. Los agentes se autentican contra el proxy con una clave de API asignada al tenant. Los operadores se autentican contra la API con un JWT. Dos superficies, dos tipos de credencial.
Cómo se emiten los tokens
Se soportan dos flujos:
1. Flujo OTP (contraseña de un solo uso)
Para tenants sin SSO. El operador inicia sesión con correo; la API envía un OTP por correo; el operador envía el OTP y recibe un JWT de corta duración más un token de refresco de mayor duración.
2. SAML / OIDC (single sign-on)
Para tenants con un proveedor de identidad (Okta, Azure AD, Google Workspace, etc.). El operador es redirigido al IdP, vuelve con una assertion y la API la intercambia por el mismo par JWT/refresh-token.
Tiempos de vida de los tokens
- JWT de acceso: corta duración (15 minutos por defecto). Va en
Authorization: Bearer …en cada llamada a la API. - Token de refresco: larga duración (30 días por defecto), usado para generar nuevos JWTs de acceso sin volver a pedir al operador. Los tokens de refresco están vinculados al cliente que los originó.
Ambos tiempos de vida son configurables por tenant.
Claims
El JWT incluye:
sub: ID de usuario operador.tenant_id: el tenant al que pertenece el token.roles: los roles del operador (p. ej.admin,member).permissions: permisos detallados resueltos a partir de la asignación de rol.exp/iat: claims estándar de expiración y emisión.jti: ID único del token, registrado en el log de auditoría al usarse.
Revocación
Los tokens de refresco pueden revocarse desde la consola (por sesión o todas las sesiones de un operador). Los JWTs de acceso son de corta duración y no son revocables individualmente; si necesitas un corte inmediato, revoca el token de refresco y el de acceso expira en minutos.
Credenciales de operador vs agente
| JWT de operador | Clave de API de agente | |
|---|---|---|
| Usado contra | API de plataforma | Proxy |
| Emitido por | Flujo OTP / SSO | Consola (por agente) |
| Tiempo de vida | Minutos (refrescable) | Hasta revocación manual |
| Identifica | Un operador humano | Un agente registrado |
| Alcance | Un tenant | Un único agente |
Nunca uses una clave de API de agente contra la API de plataforma, y nunca pongas un JWT en el código de un agente. Las dos superficies imponen esta separación.
A dónde ir después
- Visión general de la API
- Conceptos de la API
- Solicitar acceso: para la referencia completa de endpoints.