Tokens de servicio
3 min de lectura
Los tokens de servicio permiten que un programa se autentique contra Kujira sin utilizar la cuenta de una persona. Úsalos para una integración propia, un pipeline de CI/CD, una automatización interna o un agente externo que trabaje con la API.
Cada token pertenece a una única organización y sus acciones quedan identificadas como realizadas por ese servicio en el registro de actividad.
Crear un token
Al crear un token, asigna un nombre que identifique su finalidad —por ejemplo, ci-despliegue o integracion-crm— y selecciona exclusivamente los permisos que necesita. El valor completo comienza por kjtk_live_.
Copia el secreto en ese momento
El secreto se muestra una sola vez. Kujira conserva únicamente una versión protegida para validarlo, por lo que no se puede recuperar después. Si se pierde o sospechas que se ha expuesto, crea otro y revoca el anterior.
Diseñarlo con el mínimo acceso
Un token no hereda el rol de quien lo usa: actúa únicamente con los permisos que le hayas concedido. Además, no puedes crear un token con permisos más amplios que los tuyos.
Solo el propietario o un administrador puede crear tokens: un token llega a todos los agentes, credenciales y dispositivos de la organización, sin las restricciones por agente de un operador. Un token con acceso total no recibe automáticamente los permisos sensibles que Kujira añada más adelante; hay que dárselos.
Permisos concretos
Concede solo las acciones necesarias, como consultar agentes o enviar una entrada a un agente concreto.
Caducidad
Define una fecha de expiración para accesos temporales. Si no la indicas, el token seguirá activo hasta que lo revoques.
Direcciones IP
Cuando el servicio opera desde direcciones conocidas, limita el token a esas IP para impedir su uso desde otra ubicación.
Un token por integración
No compartas un único token entre varios sistemas. Un token por integración, con un nombre y permisos propios, facilita revisarlo, rotarlo o revocarlo sin interrumpir los demás servicios.
Revisar, editar, rotar y revocar
La lista muestra el nombre, los permisos, la caducidad y la última vez que se utilizó cada token. Revisa periódicamente los accesos que ya no tengan uso.
Puedes editar el nombre, los permisos, la caducidad y las IPs de un token sin cambiar su secreto, así que no tienes que tocar el servicio que lo utiliza. Los cambios se aplican en la siguiente petición. Solo puedes darle permisos que tú también tengas.
El secreto, en cambio, no se puede modificar. Para rotarlo, crea uno nuevo, actualiza el servicio que lo utiliza y revoca el anterior cuando hayas confirmado que el cambio funciona. La revocación es inmediata.
Usarlo con un agente externo
Puedes entregar un token limitado a un agente de programación para que opere Kujira mediante la API. La instrucción de conexión disponible en esta documentación le permite cargar el contrato y el flujo de autenticación; el token, en cambio, debes crearlo y custodiarlo tú.
Consulta Usar la API para ver el formato de autenticación y el alcance de cada endpoint.
Permisos para gestionarlos
| Acción | Permiso |
|---|---|
| Consultar los tokens existentes | service_token.view |
| Crear o editar un token | service_token.create |
| Revocar un token | service_token.delete |