Documentación
Credenciales
Cómo se crean, se acotan, se rotan y se revocan desde la aplicación.
Las credenciales se administran en la aplicación, no por API: crear una es una decisión de una persona sobre su propio acceso, y la API pública no puede fabricarse más acceso a sí misma. Se encuentran en Perfil → API e integraciones.
Dos tipos
| Tipo | Quién la crea | Vencimiento |
|---|---|---|
Personal (user) | Cualquier usuario con el permiso api_tokens.manage.own, desde su perfil. Actúa con su acceso. | Obligatorio. Máximo 365 días. |
De organización (admin) | Un administrador con api_tokens.manage.company. Queda anclada al administrador que la creó. | Opcional: su vida ya está atada a que el titular conserve la capacidad de administrador. |
Una credencial `admin` se revoca sola
Si el titular pierde la capacidad de administrador —cambio de rol, permiso quitado en la matriz, rol borrado— la credencial se revoca en el acto, en el primer request que la use. No queda esperando a que alguien la revise.
Acotar por recurso
Además de los scopes, una credencial puede limitarse a recursos concretos. Hay cuatro tipos y cada uno tiene su propio modo:
| Tipo de recurso | Qué acota |
|---|---|
workspace | Bibliotecas y sus archivos, y los adjuntos de un turno. |
skill | Habilidades visibles y adjuntables. |
area | Áreas visibles, y las que se pueden asignar al crear reglas o bibliotecas. |
mcp_server | Conectores que un turno puede usar. |
| Modo | Significado |
|---|---|
unrestricted | Todo lo que el usuario alcance en cada momento, no una foto del día del alta. Si mañana le dan acceso a una biblioteca nueva, la credencial la ve. |
allowlist | Solo los ids listados, y además intersectados con el acceso vivo del usuario. Una lista vacía no da acceso a nada. |
Nota
Una credencial en allowlist sobre un tipo no puede crear recursos nuevos de ese tipo: intentarlo devuelve 403 api_v1_resource_policy_create_denied. Acotar a una lista y a la vez permitir agregarle elementos sería contradictorio.
Duración del access token
Cada credencial define cuánto dura el token que emite: entre 60 segundos y 24 horas, con 1 hora por defecto. Un token nunca sobrevive a su credencial: si a la credencial le quedan diez minutos, el token sale con diez minutos.
Rotar el secreto
Rotar genera un client_secret nuevo y mata los tokens vivos de esa credencial en el request siguiente, sin esperar a que venzan. El client_id no cambia.
No se puede desplegar el secreto nuevo antes de rotar
El secreto nuevo lo genera la rotación: no existe antes, y no hay dos secretos válidos a la vez. Rotar tiene por definición una ventana de 401 que va desde la rotación hasta que terminás de desplegar el secreto que te devolvió. Es el camino de emergencia: si el secreto se filtró, esa ventana es el precio correcto.
Para rotar sin corte, no rotes: usá una credencial paralela.
- Creá una credencial nueva con los mismos scopes y las mismas restricciones de recursos.
- Desplegá su
client_idyclient_secret. Las dos credenciales funcionan a la vez. - Verificá en
last_used_atque el tráfico pasó a la nueva. - Revocá la vieja.
Nota
Un turno en curso no se corta a mitad de camino por una rotación: lo que deja de valer es el access token, así que el siguiente request es el que falla. Reintentar después de pedir un token nuevo con el secreto nuevo funciona.
- Rotá si el secreto se filtró, si se fue alguien que lo conocía, o de forma periódica.
- Una credencial revocada no se puede rotar: hay que crear una nueva.
- Si dos personas rotan a la vez, la segunda recibe un conflicto en vez de dejar a alguien con un secreto que ya no autentica.
Revocar
Hay dos cosas distintas que se pueden revocar, y conviene no confundirlas:
| Qué | Dónde | Efecto |
|---|---|---|
| Un access token | `POST /api/oauth/revoke` | Ese token deja de valer. La credencial sigue viva y puede emitir otros. |
| La credencial | La aplicación | Se cortan todos sus tokens y no puede emitir nuevos. Es irreversible. |
Qué queda registrado
Cada request de la API deja una fila de auditoría —incluidos los rechazados, porque un 401 repetido de un cliente mal configurado es justo lo que hay que poder ver—. Se guarda por 90 días.
request_id, método, plantilla de ruta, status, duración, IP y user agent.- Credencial, empresa, usuario y scopes que la operación exigió.
- Para un turno: chat, mensaje, modo de permisos y tokens consumidos.
Lo que NO se guarda
Ni el Authorization, ni el formulario de OAuth, ni el Idempotency-Key en claro —solo su hash—. Podés usar un id de negocio tuyo como key sin que ese valor quede en nuestras tablas.
La credencial también registra su last_used_at, con el que se detecta una integración que quedó apagada — o una que sigue viva y ya nadie recuerda.