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	Standaard 10 actieve keys per bedrijf; per bedrijf instelbaar in de addon-instellingen (`max_active_keys`). De geldende waarde staat in het dashboard.
Verloopdatum	Optioneel bij het aanmaken (90 / 180 / 365 dagen of zonder verloopdatum). Heeft het bedrijf `default_expiration_days` ingesteld en vraag je geen expliciete verloopdatum, dan verloopt de key alsnog volgens dat beleid.

Controleer expires_at in het antwoord op het aanmaken. Dat is de enige betrouwbare bron: ook zonder gevraagde verloopdatum kan het beleid default_expiration_days van je bedrijf er een hebben gezet. Noteer hem en plan de rotatie in.

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.

Het uitschakelen van de Public API-addon trekt ALLE API-keys van het bedrijf in (reden addon_disabled) en verwijdert het sandboxbedrijf met alle data. Opnieuw inschakelen brengt ze niet terug: je moet nieuwe keys uitgeven. Zie levenscyclus.

Rotatie

Er is atomaire rotatie: één klik in het Kinmu-dashboard (Developers → API keys) geeft de vervangende key uit met behoud van scopes, naam, omgeving en verloopbeleid en trekt de oude in dezelfde transactie in. Het nieuwe secret zie je één keer, net als bij het aanmaken. De /v1-API biedt geen keybeheer: aanmaken, roteren en intrekken gaat altijd via het dashboard.

Een al ingetrokken key kun je niet roteren: maak een nieuwe aan om hem te vervangen.

Wil je liever beide keys laten overlappen om zonder downtime te deployen, doe het dan handmatig:

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.

Keys en webhooks intrekken (DELETE) werkt ook als het abonnement inactief is: het is een beveiligingsmaatregel, geen dienstverbruik. Je kunt een gecompromitteerde credential dus altijd stilleggen.

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`	Bedrijf opgeschort of gearchiveerd, geen abonnement, opgeschort abonnement, verlopen proefperiode, of een opgezegd en verstreken of verlopen abonnement. Altijd 403, nooit 402.
403	`addon_disabled`	De addon Public API is niet actief.

Zie het volledige foutformaat in Conventies → Fouten.