API Key Scopes

Kurzfassung

• Globale Keys gehören dem Tenant. Sie tragen exakt die API-Scopes, die beim Erstellen ausgewählt wurden. Geeignet für Service-Accounts.
• Nutzergebundene Keys gehören einem konkreten Nutzer. Ihr effektiver Scope ist die Schnittmenge aus den gespeicherten Key-Scopes und den aktuellen Berechtigungen des Eigentümers — bei jedem Request live ausgewertet. Geeignet, wenn die Automatisierung die Befugnisse einer realen Person abbilden soll.
• Eine Deaktivierung des Eigentümers, ein Berechtigungsentzug oder eine Gruppenmitgliedschafts-Änderung wirken auf nutzergebundene Keys innerhalb von 60 Sekunden.

Warum zwei Scope-Typen?

Ursprünglich war jeder Key tenantweit. Das funktioniert für Monitoring-Agents und CI-Jobs, schafft aber zwei Probleme bei Keys, die die Automatisierung einer Person darstellen:

1. Geist-Berechtigungen. Ein Mitarbeiter verlässt das Unternehmen, der Admin deaktiviert das Konto — der persönliche API-Key des Mitarbeiters funktioniert aber so lange weiter, bis ihn jemand manuell widerruft.
2. Veraltete Snapshots. Der Key wurde mit assets:write erstellt. Monate später wurde der Nutzer auf Read-only zurückgestuft — der Key gewährt aber weiterhin Schreibrechte.

Nutzerbasierte Keys lösen beides, indem sie an das Benutzerkonto gebunden sind und die Berechtigungen live neu auswerten.

Berechtigungs-Schnittmenge (nutzergebundene Keys)

Ein nutzergebundener Key trägt einen beim Erstellen festgelegten Scope-Satz (z. B. ["assets:read", "assets:write"]). Bei jedem Request prüft die Auth-Middleware:

1. Ist das Benutzerkonto des Eigentümers aktiv? Wenn nicht → Zugriff verweigert.
2. Ermittlung der aktuellen Berechtigungen des Eigentümers (Aktualisierung innerhalb von 60 Sekunden).
3. Mapping benannter Berechtigungen auf API-Scopes:
   • admin → alle acht API-Scopes (Wildcard)
   • assets:write → assets:read + assets:write
   • assets:use → assets:read
   • users:manage → users:read + users:write
   • processes:manage → processes:read + processes:write
   • processes:use → processes:read
   • tickets:manage / tickets:admin → tickets:read + tickets:write
   • tickets:create / tickets:close → tickets:read
4. Der effektive Scope-Satz ist die Schnittmenge aus den Key-Scopes und den live aufgelösten API-Scopes des Eigentümers.

Ein Key kann nie mehr gewähren als der Eigentümer aktuell besitzt. Fehlt der erforderliche Scope in der Schnittmenge, antwortet die API mit 403 INSUFFICIENT_SCOPE.

Aktualisierungsverhalten

Eigentümer-Berechtigungen werden bis zu 60 Sekunden zwischengespeichert. Bei Änderungen an Gruppenmitgliedschaften oder Gruppenberechtigungen wird der Zwischenspeicher sofort aktualisiert — eine entzogene Berechtigung wirkt damit beim nächsten Request.

Eigentümer-Regeln beim Erstellen

Aufrufer	scope_type	user_id	Ergebnis
beliebig	(fehlt)	—	400 SCOPE_REQUIRED
Admin	global	null	201
Admin	global	nicht-null	400 VALIDATION_ERROR
Nicht-Admin	global	—	403 GLOBAL_KEY_ADMIN_ONLY
Admin	user	Tenant-Mitglied	201
Admin	user	Cross-Tenant	400 INVALID_USER
Nicht-Admin	user	sich selbst	201
Nicht-Admin	user	jemand anderes	403 FORBIDDEN

scope_type hat keinen Standardwert. Der Aufrufer muss immer explizit wählen.

Eigentümer-Lebenszyklus

Ereignis	Wirkung auf nutzergebundene Keys
Eigentümer aus Berechtigungsgruppe entfernt	Effektiver Scope schrumpft innerhalb 60 s
Eigentümer deaktiviert	Nächster Request wird abgelehnt
Eigentümer gelöscht	Key wird automatisch entfernt
Admin widerruft den Key explizit	Key wird deaktiviert

Wann welchen Scope?

Wähle Global, wenn:

• Der Key einen Service repräsentiert, keine Person (CI, Backups, Monitoring).
• Der Key auch dann weiterlaufen soll, wenn ein einzelner Mitarbeiter geht.
• Die Integration einen breiten Scope braucht, der bewusst nicht an eine Rolle gebunden ist.

Wähle Nutzer-gebunden, wenn:

• Der Key die Automatisierung einer Person darstellt (eigene CLI, Browser-Erweiterung, IFTTT).
• Der Key Rollenwechseln des Nutzers automatisch folgen soll.
• Off-Boarding den Key als Seiteneffekt der Nutzer-Deaktivierung mitdeaktivieren soll.

Im Zweifel: nutzergebunden bevorzugen. Der „Geist-Berechtigungen"-Failure-Mode tritt deutlich häufiger auf als die Fälle, in denen ein globaler Key wirklich gefordert ist.