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 | Massimo 10 chiavi attive per azienda. |
| Scadenza | Opzionale (90 / 180 / 365 giorni o senza scadenza). |
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.
Rotazione
Ruotare una chiave = crearne una nuova e revocare la vecchia. Flusso senza downtime:
- 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.
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 | L’abbonamento dell’azienda è sospeso. |
| 403 | addon_disabled | L’addon Public API non è attivo. |
Trovi il formato completo degli errori in Convenzioni → Errori.