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 | Las keys nuevas caducan a los 365 días salvo que elijas otro plazo (90 o 180 días) o sin caducidad al crearlas. Si tu empresa ha fijado otra política (default_expiration_days), se aplica esa. Consulta expires_at y programa la rotación con margen. |
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.
PATCH /v1/employees/{id} y POST /v1/employees/{id}/terminate rechazan empleados con rol administrativo con 403 invalid_scope, aunque la key tenga scope de escritura. Una termination_date futura devuelve 422 validation_failed: v1 no programa bajas.
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 | La empresa no tiene servicio activo: suscripción suspendida, prueba terminada o primer pago sin completar. Una cancelación surte efecto según las condiciones del contrato. |
| 403 | addon_disabled | El addon Public API no está activo. |
| 429 | rate_limited | Demasiados intentos fallidos desde la misma IP: 60 en un minuto. Espera los segundos de Retry-After. |
Consulta el formato completo de errores en Convenciones → Errores.