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	Max 10 aktiva nycklar per företag.
Utgång	Valfri (90 / 180 / 365 dagar eller utan utgångsdatum).

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.

Rotation

Att rotera en nyckel = skapa en ny och återkalla den gamla. Flöde utan driftstopp:

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.

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öretagets prenumeration är pausad.
403	`addon_disabled`	Addonet Public API är inte aktivt.

Det fullständiga felformatet finns i Konventioner → Fel.