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	Standardmäßig 10 aktive Keys pro Unternehmen; pro Unternehmen in den Addon-Einstellungen konfigurierbar (`max_active_keys`). Den geltenden Wert siehst du im Dashboard.
Ablauf	Beim Erstellen optional (90 / 180 / 365 Tage oder ohne Ablauf). Hat das Unternehmen `default_expiration_days` gesetzt und forderst du kein explizites Ablaufdatum an, läuft der Key trotzdem ab — nach dieser Richtlinie.

Prüfe expires_at in der Antwort auf die Erstellung. Das ist die einzige verlässliche Quelle: Auch ohne angefordertes Ablaufdatum kann die Richtlinie default_expiration_days deines Unternehmens eines gesetzt haben. Notiere es und plane die Rotation ein.

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.

Das Deaktivieren des Public-API-Addons widerruft ALLE API-Keys des Unternehmens (Grund addon_disabled) und löscht das Sandbox-Unternehmen samt Daten. Ein erneutes Aktivieren holt sie nicht zurück: Du musst neue Keys ausstellen. Siehe Lebenszyklus.

Rotation

Es gibt eine atomare Rotation: Ein Klick im Kinmu-Dashboard (Entwickler → API keys) stellt den Ersatz-Key aus — mit denselben Scopes, demselben Namen, derselben Umgebung und derselben Ablauf-Richtlinie — und widerruft den alten in derselben Transaktion. Das neue Secret bekommst du wie bei einer Erstellung nur ein einziges Mal zu sehen. Das /v1 bietet keine Key-Verwaltung: Erstellen, Rotieren und Widerrufen läuft immer über das Dashboard.

Ein bereits widerrufener Key lässt sich nicht rotieren: Erstelle für den Ersatz einen neuen.

Wenn du beide Keys für ein Deployment ohne Downtime überlappen lassen willst, mach es von Hand:

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.

Keys und Webhooks zu widerrufen (DELETE) funktioniert auch bei inaktivem Abonnement: Das ist eine Sicherheitsmaßnahme, keine Nutzung des Service. Du stehst nie ohne Möglichkeit da, eine kompromittierte Credential abzuschalten.

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`	Unternehmen ausgesetzt oder archiviert, kein Abonnement, ausgesetztes Abonnement, abgelaufene Testphase oder gekündigtes und abgelaufenes bzw. verfallenes Abonnement. Immer 403, nie 402.
403	`addon_disabled`	Das Addon Public API ist nicht aktiv.

Das vollständige Fehlerformat findest du unter Konventionen → Fehler.