Authentifizierung und API-Keys
Die API verwendet Unternehmens-API-Keys (Service-Accounts, nicht an einen Benutzer gebunden). Jeder Request authentifiziert sich mit dem Key als Bearer-Token:
curl https://api.kinmu.app/v1/organization \
-H "Authorization: Bearer kinmu_sk_live_xxxxxxxx"Eigenschaften der Keys
Das Unternehmen wird immer aus dem Key aufgelöst: Du sendest nie eine companyId in der URL oder im Body.
| Aspekt | Detail |
|---|---|
| Format | kinmu_sk_live_<40+ chars> (Produktion) · kinmu_sk_test_<40+ chars> (Sandbox). |
| Sichtbarkeit | Wird beim Erstellen nur ein einziges Mal angezeigt. Danach siehst du nur noch den Präfix + die ersten Zeichen. |
| Ausstellung | Über das Dashboard my.kinmu.app → Entwickler (nur global_admin / company_manager). |
| Limit | Maximal 10 aktive Keys pro Unternehmen. |
| Ablauf | Optional (90 / 180 / 365 Tage oder ohne Ablauf). |
Scopes
Jeder Key trägt explizite Scopes (Least Privilege). Ohne den erforderlichen Scope antwortet der Endpoint mit 403 invalid_scope.
| Scope | Erlaubt |
|---|---|
org:empleados:read | Mitarbeitende lesen. |
org:empleados:write | Mitarbeitende anlegen, aktualisieren und austragen. |
org:fichajes:read | Stempelungen und Work Summaries lesen. |
org:fichajes:write | Stempelungen erfassen. |
org:ausencias:read | Abwesenheiten lesen. |
org:ausencias:write | Abwesenheiten erstellen, genehmigen und ablehnen. |
org:saldos:read | Urlaubssalden lesen. |
org:estructura:read | Locations und Units lesen. |
org:informes:read | Reports anfordern und herunterladen. |
webhooks:manage | Ausgehende Webhooks verwalten. |
GET /v1/organization erfordert keinen bestimmten Scope: Er dient der Introspektion und dem Validieren des Keys. Reports verlangen zusätzlich den Lese-Scope ihrer Domäne: z. B. erfordert absences_export den Scope org:ausencias:read.
Gib jeder Integration nur die Scopes, die sie braucht.
Sandbox
Keys mit kinmu_sk_test_ arbeiten immer auf einem Sandbox-Unternehmen mit synthetischen Daten, isoliert von deinen echten Daten. Siehe den Sandbox-Guide.
Rotation
Einen Key rotieren = einen neuen erstellen und den alten widerrufen. Der Ablauf ohne Downtime:
- Erstelle den neuen Key mit denselben Scopes.
- Deploye deine Integration mit dem neuen Key.
- Verifiziere, dass sie funktioniert (z. B. mit
GET /v1/organization). - Widerrufe den alten Key.
Widerruf
Der Widerruf über das Dashboard wirkt sofort: Der Key funktioniert ab dem nächsten Request nicht mehr (401 unauthenticated). Widerrufe jeden Key umgehend, den du für kompromittiert hältst, und prüfe seine last_used_ip.
Best Practices
- Veröffentliche einen Key niemals in Client-Code, mobilen Apps, Repositories oder Logs. Es sind Server-Credentials.
- Bewahre Keys in einem Secrets-Manager oder in Umgebungsvariablen auf.
- Verwende einen Key pro Integration, um granular widerrufen zu können.
- Wende Least Privilege an: nur die unbedingt nötigen Scopes.
- Konfiguriere ein Ablaufdatum und rotiere regelmäßig.
- Protokolliere in Logs niemals den Header
Authorization.
Authentifizierungsfehler
| HTTP | code | Ursache |
|---|---|---|
| 401 | unauthenticated | Key fehlt, ist ungültig, widerrufen oder abgelaufen. |
| 403 | invalid_scope | Der Key hat den erforderlichen Scope nicht (errors.required_scope). |
| 403 | subscription_inactive | Das Abonnement des Unternehmens ist ausgesetzt. |
| 403 | addon_disabled | Das Addon Public API ist nicht aktiv. |
Das vollständige Fehlerformat findest du unter Konventionen → Fehler.