Authenticatie en API-keys

De API gebruikt API-keys op bedrijfsniveau (service accounts, niet gekoppeld aan een gebruiker). Elke request authenticeer je met de key als Bearer token:


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

Aard van de keys

Het bedrijf wordt altijd afgeleid uit de key: je stuurt nooit een companyId mee in de URL of de body.

Aspect	Details
Formaat	`kinmu_sk_live_<40+ chars>` (productie) · `kinmu_sk_test_<40+ chars>` (sandbox).
Zichtbaarheid	Wordt maar één keer getoond bij het aanmaken. Daarna zie je alleen de prefix + de eerste tekens.
Uitgifte	Via het dashboard my.kinmu.app → Developers (alleen `global_admin` / `company_manager`).
Limiet	Maximaal 10 actieve keys per bedrijf.
Verloopdatum	Optioneel (90 / 180 / 365 dagen of zonder verloopdatum).

Scopes

Elke key heeft expliciete scopes (least privilege). Zonder de vereiste scope antwoordt het endpoint met 403 invalid_scope.

Scope	Geeft toegang tot
`org:empleados:read`	Medewerkers lezen.
`org:empleados:write`	Medewerkers aanmaken, bijwerken en uit dienst melden.
`org:fichajes:read`	Check-ins en work-summaries lezen.
`org:fichajes:write`	Check-ins registreren.
`org:ausencias:read`	Afwezigheden lezen.
`org:ausencias:write`	Afwezigheden aanmaken, goedkeuren en afwijzen.
`org:saldos:read`	Verlofsaldi lezen.
`org:estructura:read`	Locations en units lezen.
`org:informes:read`	Rapporten aanvragen en downloaden.
`webhooks:manage`	Uitgaande webhooks beheren.

GET /v1/organization vereist geen specifieke scope: het dient voor introspectie en om de key te valideren. Rapporten vereisen daarnaast de leesscope van hun domein: absences_export vereist bijvoorbeeld org:ausencias:read.

Geef elke integratie alleen de scopes die ze nodig heeft.

Sandbox

Keys met kinmu_sk_test_ werken altijd op een sandboxbedrijf met synthetische data, geïsoleerd van je echte data. Zie de Sandbox-gids.

Rotatie

Een key roteren = een nieuwe aanmaken en de oude intrekken. Zo doe je het zonder downtime:

Maak de nieuwe key aan met dezelfde scopes.
Deploy je integratie met de nieuwe key.
Controleer dat alles werkt (bijv. met een GET /v1/organization).
Trek de oude key in.

Intrekken

Intrekken werkt per direct vanuit het dashboard: de key stopt met werken bij de eerstvolgende request (401 unauthenticated). Trek een key waarvan je vermoedt dat die is gecompromitteerd meteen in en controleer het last_used_ip.

Best practices

Zet een key nooit in clientcode, mobiele apps, repositories of logs. Het zijn servercredentials.
Bewaar keys in een secret manager of in environment-variabelen.
Gebruik één key per integratie, zodat je granulair kunt intrekken.
Pas least privilege toe: alleen de strikt noodzakelijke scopes.
Stel een verloopdatum in en roteer periodiek.
Log nooit de Authorization-header.

Authenticatiefouten

HTTP	`code`	Oorzaak
401	`unauthenticated`	De key ontbreekt, is ongeldig, ingetrokken of verlopen.
403	`invalid_scope`	De key mist de vereiste scope (`errors.required_scope`).
403	`subscription_inactive`	Het abonnement van het bedrijf is opgeschort.
403	`addon_disabled`	De addon Public API is niet actief.

Zie het volledige foutformaat in Conventies → Fouten.