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 | Máximo 10 keys activas por empresa. |
| Expiración | Opcional (90 / 180 / 365 días o sin expiració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.
Rotación
Rotar una key = crear una nueva y revocar la antigua. Flujo sin downtime:
- 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.
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 suscripción de la empresa está suspendida. |
| 403 | addon_disabled | El addon Public API no está activo. |
Consulta el formato completo de errores en Convenciones → Errores.