Autentisering och API-nycklar

API:et använder API-nycklar på företagsnivå (service accounts, inte knutna till en användare). Varje request autentiseras med nyckeln som Bearer token:


curl https://api.kinmu.app/v1/organization \
  -H "Authorization: Bearer kinmu_sk_live_xxxxxxxx"

Så fungerar nycklarna

Företaget härleds alltid från nyckeln: du skickar aldrig något companyId i URL:en eller i bodyn.

Aspekt	Detalj
Format	`kinmu_sk_live_<40+ chars>` (produktion) · `kinmu_sk_test_<40+ chars>` (sandbox).
Synlighet	Visas en enda gång när de skapas. Därefter ser du bara prefixet + de första tecknen.
Utfärdande	Från dashboarden my.kinmu.app → Utvecklare (endast `global_admin` / `company_manager`).
Gräns	10 aktiva nycklar per företag som standard; konfigurerbart per företag i addon-inställningarna (`max_active_keys`). Gällande värde syns i dashboarden.
Utgång	Valfri när nyckeln skapas (90 / 180 / 365 dagar eller utan utgångsdatum). Har företaget satt `default_expiration_days` och du inte ber om ett uttryckligt utgångsdatum går nyckeln ändå ut, enligt den policyn.

Kontrollera expires_at i svaret när nyckeln skapas. Det är den enda tillförlitliga källan: även utan begärt utgångsdatum kan företagets policy default_expiration_days ha satt ett. Notera det och planera in rotationen.

Scopes

Varje nyckel har explicita scopes (minsta möjliga behörighet). Utan rätt scope svarar endpointen 403 invalid_scope.

Scope	Ger
`org:empleados:read`	Läsa medarbetare.
`org:empleados:write`	Skapa, uppdatera och avsluta medarbetare.
`org:fichajes:read`	Läsa stämplingar och work-summaries.
`org:fichajes:write`	Registrera stämplingar.
`org:ausencias:read`	Läsa frånvaro.
`org:ausencias:write`	Skapa, godkänna och avslå frånvaro.
`org:saldos:read`	Läsa semestersaldon.
`org:estructura:read`	Läsa locations och units.
`org:informes:read`	Begära och ladda ner rapporter.
`webhooks:manage`	Hantera utgående webhooks.

GET /v1/organization kräver inget specifikt scope: den används för introspektion och för att validera nyckeln. Rapporter kräver dessutom läs-scopet för sin domän: t.ex. kräver absences_export scopet org:ausencias:read.

Ge varje integration endast de scopes den behöver.

Sandbox

Nycklar med kinmu_sk_test_ opererar alltid på ett sandbox-företag med syntetiska data, isolerat från dina riktiga data. Se Sandbox-guiden.

Att stänga av Public API-addonen återkallar ALLA företagets API-nycklar (orsak addon_disabled) och raderar sandbox-företaget med alla dess data. Att slå på den igen återuppväcker dem inte: nya nycklar måste utfärdas. Se livscykel.

Rotation

Det finns atomisk rotation: ett klick i Kinmus dashboard (Utvecklare → API keys) utfärdar ersättningsnyckeln med samma scopes, namn, miljö och utgångspolicy och återkallar den gamla i samma transaktion. Den nya hemligheten visas en enda gång, precis som när en nyckel skapas. /v1 exponerar ingen nyckelhantering: att skapa, rotera och återkalla nycklar görs alltid från dashboarden.

En redan återkallad nyckel går inte att rotera: skapa en ny för att ersätta den.

Vill du hellre låta båda nycklarna överlappa för att driftsätta utan avbrott, gör det för hand:

Skapa den nya nyckeln med samma scopes.
Driftsätt din integration med den nya nyckeln.
Verifiera att den fungerar (t.ex. med ett GET /v1/organization).
Återkalla den gamla nyckeln.

Återkallelse

Återkallelsen sker omedelbart från dashboarden: nyckeln slutar fungera vid nästa request (401 unauthenticated). Återkalla direkt varje nyckel du misstänker är komprometterad och granska dess last_used_ip.

Att återkalla nycklar och webhooks (DELETE) fungerar även med inaktiv prenumeration: det är en säkerhetsåtgärd, inte tjänsteanvändning. Du står aldrig utan möjlighet att stänga av en komprometterad credential.

Bästa praxis

Publicera aldrig en nyckel i klientkod, mobilappar, repos eller loggar. Nycklarna är servercredentials.
Förvara dem i en secrets manager eller i miljövariabler.
Använd en nyckel per integration så att du kan återkalla granulärt.
Tillämpa minsta möjliga behörighet: bara de scopes som verkligen krävs.
Sätt utgångsdatum och rotera regelbundet.
Logga aldrig headern Authorization.

Autentiseringsfel

HTTP	`code`	Orsak
401	`unauthenticated`	Nyckeln saknas, är ogiltig, återkallad eller utgången.
403	`invalid_scope`	Nyckeln saknar det scope som krävs (`errors.required_scope`).
403	`subscription_inactive`	Företaget pausat eller arkiverat, ingen prenumeration, pausad prenumeration, utgången testperiod, eller uppsagd och utlöpt eller förfallen prenumeration. Alltid 403, aldrig 402.
403	`addon_disabled`	Addonet Public API är inte aktivt.

Det fullständiga felformatet finns i Konventioner → Fel.