Autenticación y llaves
Cada llamada lleva una llave de la empresa en la cabecera Authorization:
GET /api/v1/reports/summary/?date_from=2026-10-01&date_to=2026-10-31 HTTP/1.1
Host: app.kabal-attendance.com
Authorization: Bearer kba_4Hq0x9mT1vZp8bLwYc3RkN7sJ2dF6gAeU5oXiQyKtMh
No hay cookies, sesiones ni tokens que refrescar: la llave es la credencial entera, y funciona hasta que vence o alguien la revoca.
La llave es de la empresa
Una llave no está atada a la persona que la creó. Lee a todos los empleados de todas las sedes de la empresa, y sigue funcionando si esa persona deja la empresa o pierde su acceso a la app. Por eso solo un administrador que ve la empresa entera puede crear o revocar una: un usuario limitado a algunas sedes ve la lista de llaves y nada más.
Lo que una llave puede hacer es fijo: leer el Resumen y el Detalle. No escribe nada, no lee fotos y no llama ninguna otra ruta de la app; una llave mandada a otra ruta recibe un 401.
Crear, vencer, revocar
Las llaves se manejan en la app, en API:
- Crear. Un nombre y un vencimiento: 30, 90 o 365 días, una fecha a su elección, o sin vencimiento. Una llave que vence en una fecha funciona ese día entero, en la zona horaria de la empresa. La llave se muestra una sola vez.
- La lista muestra el nombre de cada llave, sus primeros caracteres (
kba_a1b2c3d4…, para reconocerla), su estado (activa, vencida, revocada), quién la creó y cuándo, su vencimiento y cuándo se usó por última vez. El último uso se actualiza como mucho una vez por minuto. - Revocar. Detiene la llave en el acto. Una llave revocada se queda en la lista como registro y no se puede reactivar; se crea otra.
Cada plan dice cuántas llaves vivas puede tener una empresa. Las vencidas y las revocadas no cuentan.
Para cambiar una llave sin un hueco: cree la nueva, póngala en su sistema, compruebe una llamada con ella y después revoque la anterior.
Cuándo se rechaza una llave
La respuesta es siempre un sobre JSON con un code estable para su programa y un detail en español para una persona:
{ "detail": "La llave del API venció.", "code": "api_key_expired" }
| Estado | code | Qué pasó | Qué hacer |
|---|---|---|---|
| 401 | not_authenticated | No se mandó llave, o no se mandó como Authorization: Bearer. | Mandar la cabecera. |
| 401 | api_key_invalid | La llave no existe o fue revocada. Las dos se responden igual a propósito. | Pedir una llave nueva al administrador. |
| 401 | api_key_expired | La llave pasó su fecha de vencimiento. | Pedir una llave nueva al administrador. |
| 401 | company_suspended | La empresa está suspendida o se cerró. La llave no cambió. | Hablar con el administrador de la empresa. |
| 403 | api_not_included | El plan de la empresa no incluye el API. La llave vuelve a funcionar sola si el plan lo incluye otra vez. | El administrador cambia el plan. |
Todo 401 lleva WWW-Authenticate: Bearer realm="integration".
Una empresa cuya suscripción de pago venció sigue leyendo: el API responde como siempre mientras la app está en solo lectura.
Llaves inválidas desde una dirección
Kabal cuenta las llaves rechazadas que llegan desde cada dirección IP. Después de 30 en un minuto, toda llamada desde esa dirección recibe un 429 throttled hasta que el minuto termina, también las que traen una llave buena: no repita un 401 en un ciclo. Ver Límites.
Guarde la llave en secreto
- Guárdela en su gestor de secretos o en una variable de entorno, nunca en un repositorio ni en una URL.
- Mándela solo a
https://app.kabal-attendance.com. Kabal nunca la pide por correo, chat o teléfono. - Si pudo filtrarse, revóquela en la app y cree otra.