Authentifizierung und API-Schlüssel

Die öffentliche Kabeen-API authentifiziert jede Anfrage mit einem API-Schlüssel — einem Workspace-gebundenen Bearer-Credential. Es gibt keinen OAuth-Flow, kein Session-Cookie und keinen Login-Schritt: Ein Workspace-Admin erstellt einen Schlüssel einmalig in der Kabeen-Anwendung, und Sie legen ihn bei jeder Anfrage vor.

So funktioniert es

• Ein API-Schlüssel gehört zu genau einem Workspace. Der Workspace wird bei der Erstellung an den Schlüssel gebunden und wird nie im Pfad, im Query-String oder im Body übergeben — jeder Endpunkt arbeitet implizit auf „dem Workspace, zu dem dieser Schlüssel gehört".
• Ein Schlüssel trägt einen festen Satz von Berechtigungs-Scopes (z. B. applications:read, infrastructure:edit). Jeder Endpunkt erfordert genau einen Scope, dokumentiert in der Endpunkt-Referenz.
• Schlüssel werden von einem Workspace-Admin innerhalb der Kabeen-Anwendung erstellt, rotiert und widerrufen — die öffentliche API selbst stellt keinen Endpunkt zur Schlüsselverwaltung bereit.
• Sämtlicher Verkehr der öffentlichen API wird als Service-Akteur (der Schlüssel) authentifiziert, nie als menschliches Mitglied. Audit-Log-Einträge für öffentliche API-Aufrufe verzeichnen den Schlüssel als Akteur.

Vorlegen des Schlüssels

Jeder generierte Schlüssel beginnt mit dem Präfix kbn_ (in der Praxis kbn_live_...). Die API akzeptiert den Schlüssel über zwei gleichwertige Transportwege — nutzen Sie den, der besser zu Ihrem HTTP-Client passt:

Beide werden vom selben Authentifizierungsmechanismus erkannt, ausschließlich auf Pfaden unter /public/. Sind beide Header vorhanden, hat X-Api-Key Vorrang.

curl https://app.kabeen.io/public/v1/me \
  -H "Authorization: Bearer kbn_live_51gv9c2b7f2a4e6f8c1a0d3b6e9f2c5a8"

curl https://app.kabeen.io/public/v1/me \
  -H "X-Api-Key: kbn_live_51gv9c2b7f2a4e6f8c1a0d3b6e9f2c5a8"

Introspektion: GET /me

Bevor Sie irgendetwas anderes anbinden, rufen Sie GET /public/v1/me auf. Der Aufruf erfordert nur einen gültigen Schlüssel (keinen bestimmten Scope) und sagt Ihnen genau, an welchen Workspace Sie gebunden sind und was der Schlüssel kann — nützlich sowohl als „Funktioniert mein Schlüssel"-Smoke-Test als auch für Integrationen, die sich an die gewährten Scopes anpassen.

{
  "workspace": {
    "id": "3f9c9f2e-8a71-4e2a-9b0d-2c5f6a1d7e44",
    "name": "Acme Corp"
  },
  "key": {
    "id": "8b2e6a4d-1c3f-4a9e-9d7b-5f0e2c8a6b31",
    "name": "Finance integration",
    "alias": "read"
  },
  "permissions": [
    "applications:read",
    "contracts:read",
    "data:read",
    "infrastructure:read"
  ]
}

• workspace — der Workspace, an den dieser Schlüssel gebunden ist (Id + Anzeigename).
• key — die Metadaten des Schlüssels selbst: id, name und alias (der Alias, aus dem er erstellt wurde — read, write oder admin — oder null, wenn der Schlüssel aus einem benutzerdefinierten, expliziten Satz von Scopes erstellt wurde).
• permissions — die exakte, sortierte Liste der Berechtigungs-Scopes, die dieser Schlüssel gewährt. Sie ist die maßgebliche Quelle dafür, was der Schlüssel aufrufen darf; behandeln Sie sie als den Vertrag, nicht den Aliasnamen.

Berechtigungs-Scopes

Jeder Endpunkt erfordert genau einen Berechtigungs-Scope in der Form resource:action:

Aliase vs. explizite Scopes

Ein Schlüssel wird auf genau eine von zwei Arten mit Scopes versehen, festgelegt bei seiner Erstellung:

• Ein Alias — read, write oder admin — der den Berechtigungssatz der entsprechenden Systemrolle zum Erstellungszeitpunkt als Momentaufnahme übernimmt. Das Feld alias des Schlüssels (sichtbar in GET /me) hält fest, aus welchem Alias er stammt; die gewährten permissions sind jedoch die eingefrorene Momentaufnahme, keine dynamische Verknüpfung zur Rolle: Ändern sich die Berechtigungen der Rolle später, behalten bestehende Schlüssel, was ihnen gewährt wurde.
• Eine explizite Liste von resource:action-Codes. In diesem Fall ist alias gleich null.

In beiden Fällen kann einem Schlüssel nie ein Scope gewährt werden, den sein Ersteller zum Erstellungszeitpunkt nicht selbst besitzt — ein Admin kann keinen Schlüssel mit mehr Rechten ausstellen, als sein eigenes Konto hat.

Wenn ein Scope fehlt

Der Aufruf eines Endpunkts ohne den erforderlichen Scope liefert 403 Forbidden:

{
  "code": "insufficient_permission",
  "message": "missing permission: applications:edit",
  "status": 403
}

Verlassen Sie sich nicht auf fest codierte Annahmen darüber, was ein Schlüssel kann — rufen Sie GET /me auf und prüfen Sie permissions, bevor Sie einen Aufruf versuchen, oder behandeln Sie 403/insufficient_permission sauber und melden Sie es an die Person, die den Schlüssel der Integration verwaltet.

Schlüssel-Lebenszyklus und Verwaltung

API-Schlüssel werden von einem Workspace-Admin innerhalb der Kabeen-Anwendung erstellt, rotiert und widerrufen — die Schlüsselverwaltung ist nicht Teil der öffentlichen API selbst. Was Sie operativ erwarten können:

• Erstellung — ein Admin benennt den Schlüssel und weist ihm Scopes zu, entweder über einen Alias (read/write/admin) oder eine explizite Liste von Berechtigungscodes (nie beides, nie keines von beiden), optional mit Ablaufdatum. Das Klartext-Secret wird genau einmal zurückgegeben, bei der Erstellung — Kabeen speichert es nicht in wiederherstellbarer Form und kann es Ihnen nicht erneut anzeigen. Persistiert wird nur ein SHA-256-Hash des Secrets; abrufbar sind danach nur Metadaten plus ein kurzes Anzeige-Präfix des Schlüssels.
• Rotation — die Rotation eines Schlüssels erzeugt ein völlig neues Secret (erneut nur einmal angezeigt) und macht das alte Secret sofort ungültig; Id, Name und Scopes des Schlüssels bleiben erhalten.
• Widerruf — ein widerrufener oder gelöschter Schlüssel funktioniert sofort nicht mehr: Jede Anfrage sucht den Schlüssel über den Hash seines Secrets und verlangt, dass er aktuell aktiv ist — es gibt also kein Caching-Fenster und keine verzögerte Propagierung.
• Ablauf — ein Schlüssel mit Ablaufdatum authentifiziert nicht mehr, sobald dieser Zeitpunkt überschritten ist; erzwungen durch dieselbe cachefreie Prüfung pro Anfrage.

Fehlerfälle

Authentifizierungsfehler liefern in allen folgenden Fällen 401 Unauthorized:

• Es wurde gar kein Credential vorgelegt (weder Authorization: Bearer noch X-Api-Key).
• Das Credential beginnt nicht mit dem Präfix kbn_ (fehlerhaft / kein Kabeen-Schlüssel).
• Der Schlüssel passt zu keinem aktuell aktiven Schlüssel (falsch, widerrufen oder gelöscht).
• Der Schlüssel hat sein Ablaufdatum überschritten.

Ein echter 401 wird auf der Authentifizierungsebene abgewiesen, bevor der einheitliche Fehler-Body der API angehängt werden kann: Die Antwort hat einen leeren Body und einen WWW-Authenticate: Bearer realm="kbine", error="invalid_token"-Header. Versuchen Sie nicht, JSON aus einem 401 zu parsen — siehe Paginierung und Fehler.

403 Forbidden ist ein eigenständiger Fehlerfall: Der Schlüssel ist gültig und authentifiziert, ihm fehlt jedoch der Scope, den der Endpunkt erfordert.

Sicherheits-Best-Practices

• Behandeln Sie den Schlüssel als Geheimnis. Wer ihn besitzt, kann als Service-Identität in Ihrem Workspace agieren, im Rahmen der gewährten Berechtigungen.
• Committen Sie Schlüssel nie in die Versionsverwaltung und betten Sie sie nie in clientseitigen Code ein (Browser-JS, Mobile-Apps, öffentliche Repositories). Die öffentliche API ist für Server-zu-Server-Integrationen konzipiert.
• Speichern Sie Schlüssel in Umgebungsvariablen oder einem Secret-Manager, nicht in Konfigurationsdateien, die in ein Repository eingecheckt werden.
• Bevorzugen Sie Scopes nach dem Least-Privilege-Prinzip. Eine rein lesende Reporting-Integration sollte einen read-Schlüssel (oder einen benutzerdefinierten Nur-Lese-Schlüssel) erhalten, nicht admin.
• Rotieren Sie regelmäßig — und sofort nach jedem Verdacht auf Kompromittierung; die Rotation macht das alte Secret in dem Moment ungültig, in dem das neue ausgestellt wird.
• Widerrufen Sie Schlüssel, die Sie nicht mehr nutzen. Der Widerruf greift ab der nächsten Anfrage — zügiges Widerrufen verursacht also keine operativen Kosten.
• Setzen Sie ein Ablaufdatum für temporäre oder zeitlich begrenzte Integrationen, statt sich auf einen späteren manuellen Widerruf zu verlassen.