Tokens de API
Toda llamada a la API de Dashboard Mágico lleva un token: una credencial que indica qué organización está llamando. Lo envías en el header Authorization: Bearer <token> de cada solicitud.
Dónde crear el token
Los tokens se crean y se gestionan en la Cuenta Kobana, no en Dashboard Mágico. La pestaña API Tokens de Sistema › API (/dashboard/api) te lleva hasta allí:
- Abre Sistema › API, pestaña API Tokens.
- Haz clic en Ir a la creación de token. La página de tokens de la Cuenta Kobana se abre en otra pestaña.
- Crea el token allí. En la misma página revisas y revocas los tokens que ya existen.
El token vale para toda la organización. Para indicar en qué workspace actúa la llamada, usa el header X-Workspace-Id — mira API y webhooks.
Los detalles técnicos (formato del token, ambientes, errores de autenticación) están en la referencia de autenticación de la API.
:::warning Sandbox y producción tienen tokens distintos Un token de sandbox no funciona en producción, y viceversa. Crea uno para cada ambiente. :::
Cuando los tokens están en el propio Dashboard Mágico
En algunas instalaciones, la pestaña API Tokens muestra la lista de tokens y el botón Generate Token en lugar del atajo a la Cuenta Kobana. En ese caso:
- Generar — dale un nombre, una descripción, la fecha de validez (en blanco, vale por 1 año) y los correos que reciben el aviso de vencimiento. El token aparece una sola vez: cópialo y guárdalo en un gestor de secretos.
- Abrir un token — haz clic en él en la lista para ver los detalles: origen, validez, último uso y quién lo creó, modificó, deshabilitó o revocó.
| Acción | Qué pasa |
|---|---|
| Deshabilitar | El token deja de autenticar hasta que se habilite de nuevo. |
| Rotar | Genera un token nuevo, que se muestra una sola vez. El anterior sigue valiendo por 7 días y luego deja de funcionar — actualiza la integración dentro de ese plazo. |
| Revoke | Termina el token de forma definitiva. No hay vuelta atrás. |
| Eliminar | Quita de la lista un token ya revocado. El historial de auditoría se mantiene. |
Los correos registrados (o, sin ellos, quien creó el token) reciben un aviso cuando faltan 30 días para el vencimiento.
Buenas prácticas
- Un token por aplicación. Así revocas uno sin tumbar los demás sistemas.
- Cámbialos de vez en cuando. Crea el nuevo, actualiza la aplicación y solo entonces revoca el anterior.
- Nunca en el código. Guarda el token en variables de entorno o en un gestor de secretos.
Las solicitudes respetan los límites de Rate limiting.