Autenticazione e chiavi API
L’API usa chiavi API aziendali (service account, non legate a un utente). Ogni richiesta si autentica con la chiave come Bearer token:
curl https://api.kinmu.app/v1/organization \
-H "Authorization: Bearer kinmu_sk_live_xxxxxxxx"Natura delle chiavi
L’azienda si risolve sempre dalla chiave: non invii mai un companyId nell’URL né nel body.
| Aspetto | Dettaglio |
|---|---|
| Formato | kinmu_sk_live_<40+ chars> (produzione) · kinmu_sk_test_<40+ chars> (sandbox). |
| Visibilità | Vengono mostrate una sola volta alla creazione. Dopo vedrai solo il prefisso + i primi caratteri. |
| Emissione | Dalla dashboard my.kinmu.app → Sviluppatori (solo global_admin / company_manager). |
| Limite | 10 chiavi attive per azienda di default; configurabile per azienda nelle impostazioni dell’addon (max_active_keys). Il valore in vigore si vede nella dashboard. |
| Scadenza | Opzionale alla creazione (90 / 180 / 365 giorni o senza scadenza). Se l’azienda ha impostato default_expiration_days e non chiedi una scadenza esplicita, la chiave scade comunque secondo quella policy. |
Controlla expires_at nella risposta di creazione. È l’unica fonte affidabile: anche senza chiedere una scadenza, la policy default_expiration_days della tua azienda può avergliene messa una. Annotala e pianifica la rotazione.
Scopes
Ogni chiave ha scopes espliciti (minimo privilegio). Senza lo scope richiesto, l’endpoint risponde 403 invalid_scope.
| Scope | Permette |
|---|---|
org:empleados:read | Leggere i dipendenti. |
org:empleados:write | Creare, aggiornare e cessare i dipendenti. |
org:fichajes:read | Leggere timbrature e work-summaries. |
org:fichajes:write | Registrare timbrature. |
org:ausencias:read | Leggere le assenze. |
org:ausencias:write | Creare, approvare e rifiutare assenze. |
org:saldos:read | Leggere i saldi ferie. |
org:estructura:read | Leggere locations e units. |
org:informes:read | Richiedere e scaricare report. |
webhooks:manage | Gestire i webhooks in uscita. |
GET /v1/organization non richiede uno scope specifico: serve per l’introspezione e per validare la chiave. I report richiedono anche lo scope di lettura del loro dominio: ad es. absences_export richiede org:ausencias:read.
Concedi a ogni integrazione solo gli scopes di cui ha bisogno.
Sandbox
Le chiavi kinmu_sk_test_ operano sempre su un’azienda sandbox con dati sintetici, isolata dai tuoi dati reali. Vedi la guida alla Sandbox.
Disattivare l’addon Public API revoca TUTTE le API key dell’azienda (motivo addon_disabled) ed elimina l’azienda sandbox con i suoi dati. Riattivarlo non le resuscita: vanno emesse chiavi nuove. Vedi il ciclo di vita.
Rotazione
Esiste la rotazione atomica: un clic nella dashboard di Kinmu (Sviluppatori → API keys) emette la chiave sostitutiva mantenendo scopes, nome, ambiente e policy di scadenza e revoca la precedente nella stessa transazione. Il nuovo segreto lo vedi una sola volta, come in una creazione. Il /v1 non espone la gestione delle chiavi: crearle, ruotarle e revocarle si fa sempre dalla dashboard.
Una chiave già revocata non si può ruotare: per sostituirla, creane una nuova.
Se preferisci sovrapporre le due chiavi per un deploy senza downtime, fallo a mano:
- Crea la nuova chiave con gli stessi scopes.
- Fai il deploy della tua integrazione con la nuova chiave.
- Verifica che funzioni (ad es. con un
GET /v1/organization). - Revoca la chiave vecchia.
Revoca
La revoca è immediata dalla dashboard: la chiave smette di funzionare dalla richiesta successiva (401 unauthenticated). Revoca subito qualsiasi chiave che sospetti compromessa e controlla il suo last_used_ip.
Revocare chiavi e webhook (DELETE) funziona anche con l’abbonamento inattivo: è un controllo di sicurezza, non consumo del servizio. Non resti mai senza la possibilità di chiudere una credenziale compromessa.
Best practice
- Mai pubblicare una chiave in codice client, app mobile, repository o log. Sono credenziali server.
- Conservale in un secret manager o in variabili d’ambiente.
- Usa una chiave per integrazione, così puoi revocare in modo granulare.
- Applica il minimo privilegio: solo gli scopes indispensabili.
- Imposta una scadenza e ruota le chiavi periodicamente.
- Nei log, non registrare mai l’header
Authorization.
Errori di autenticazione
| HTTP | code | Causa |
|---|---|---|
| 401 | unauthenticated | Chiave assente, non valida, revocata o scaduta. |
| 403 | invalid_scope | La chiave non ha lo scope richiesto (errors.required_scope). |
| 403 | subscription_inactive | Azienda sospesa o archiviata, senza abbonamento, abbonamento sospeso, trial scaduto, oppure abbonamento disdetto e scaduto o non più valido. Sempre 403, mai 402. |
| 403 | addon_disabled | L’addon Public API non è attivo. |
Trovi il formato completo degli errori in Convenzioni → Errori.