Autenticación y API keys
La API usa API keys de empresa (service accounts, no ligadas a un usuario). Cada petición se autentica con la key como Bearer token:
curl https://api.kinmu.app/v1/organization \
-H "Authorization: Bearer kinmu_sk_live_xxxxxxxx"Naturaleza de las keys
La empresa se resuelve siempre desde la key: nunca envías un companyId en la URL ni en el body.
| Aspecto | Detalle |
|---|---|
| Formato | kinmu_sk_live_<40+ chars> (producción) · kinmu_sk_test_<40+ chars> (sandbox). |
| Visibilidad | Se muestran una sola vez al crearlas. Después solo verás el prefijo + los primeros caracteres. |
| Emisión | Desde el dashboard my.kinmu.app → Desarrolladores (solo global_admin / company_manager). |
| Límite | 10 keys activas por empresa por defecto; configurable por empresa en los ajustes del addon (max_active_keys). El valor vigente se ve en el panel. |
| Expiración | Opcional al crearla (90 / 180 / 365 días o sin expiración). Si la empresa ha fijado default_expiration_days y no pides expiración explícita, la key caduca igualmente según esa política. |
Comprueba expires_at en la respuesta de creación. Es la única fuente fiable: aunque no pidas expiración, la política default_expiration_days de tu empresa puede haberle puesto fecha. Anótala y programa la rotación.
Scopes
Cada key lleva scopes explícitos (mínimo privilegio). Sin el scope requerido, el endpoint responde 403 invalid_scope.
| Scope | Permite |
|---|---|
org:empleados:read | Leer empleados. |
org:empleados:write | Alta, actualización y baja de empleados. |
org:fichajes:read | Leer fichajes y work-summaries. |
org:fichajes:write | Registrar fichajes. |
org:ausencias:read | Leer ausencias. |
org:ausencias:write | Crear, aprobar y rechazar ausencias. |
org:saldos:read | Leer saldos de vacaciones. |
org:estructura:read | Leer locations y units. |
org:informes:read | Solicitar y descargar informes. |
webhooks:manage | Gestionar webhooks salientes. |
GET /v1/organization no requiere un scope concreto: sirve para introspección y para validar la key. Los informes exigen además el scope de lectura de su dominio: p. ej. absences_export requiere org:ausencias:read.
Concede a cada integración solo los scopes que necesita.
Sandbox
Las keys kinmu_sk_test_ operan siempre sobre una empresa sandbox con datos sintéticos, aislada de tus datos reales. Ver la guía de Sandbox.
Desactivar el addon Public API revoca TODAS las API keys de la empresa (motivo addon_disabled) y elimina la empresa sandbox con sus datos. Volver a activarlo no las resucita: hay que emitir keys nuevas. Ver ciclo de vida.
Rotación
Hay rotación atómica: un clic en el panel de Kinmu (Desarrolladores → API keys) emite la key sustituta conservando scopes, nombre, entorno y política de expiración y revoca la anterior en la misma transacción. Recibes el secreto nuevo una sola vez, como en una creación. El /v1 no expone gestión de keys: crearlas, rotarlas y revocarlas se hace siempre desde el panel.
Una key ya revocada no se puede rotar: para sustituirla, crea una nueva.
Si prefieres solapar ambas keys para desplegar sin downtime, hazlo a mano:
- Crea la nueva key con los mismos scopes.
- Despliega tu integración con la nueva key.
- Verifica que funciona (p. ej. un
GET /v1/organization). - Revoca la key antigua.
Revocación
La revocación es inmediata desde el dashboard: la key deja de funcionar en el siguiente request (401 unauthenticated). Revoca de inmediato cualquier key que sospeches comprometida y revisa su last_used_ip.
Revocar keys y webhooks (DELETE) funciona aunque la suscripción esté inactiva: es un control de seguridad, no consumo del servicio. Nunca te quedas sin poder cortar una credencial comprometida.
Buenas prácticas
- Nunca publiques una key en código cliente, apps móviles, repositorios ni logs. Son credenciales de servidor.
- Guárdalas en un gestor de secretos o variables de entorno.
- Usa una key por integración para poder revocar de forma granular.
- Aplica mínimo privilegio: solo los scopes imprescindibles.
- Configura expiración y rota periódicamente.
- En logs, nunca registres el header
Authorization.
Errores de autenticación
| HTTP | code | Causa |
|---|---|---|
| 401 | unauthenticated | Falta la key, es inválida, revocada o expirada. |
| 403 | invalid_scope | La key no tiene el scope requerido (errors.required_scope). |
| 403 | subscription_inactive | Empresa suspendida o archivada, sin suscripción, suscripción suspendida, trial caducado, o suscripción cancelada y vencida o expirada. Siempre 403, nunca 402. |
| 403 | addon_disabled | El addon Public API no está activo. |
Consulta el formato completo de errores en Convenciones → Errores.