API-Key-Scopes
Ein API-Key kann auf zwei Arten existieren: als globaler Key, der dem Mandanten gehört, oder als nutzergebundener Key, der einer konkreten Person gehört. Der Unterschied entscheidet darüber, was passiert, wenn diese Person das Unternehmen verlässt.
#Der Unterschied in einem Absatz
Ein globaler Key trägt exakt die Scopes, die beim Anlegen ausgewählt wurden — dauerhaft. Ein nutzergebundener Key trägt die Schnittmenge aus seinen Scopes und den aktuellen Berechtigungen seiner Eigentümerin oder seines Eigentümers, bei jedem Request neu ausgewertet. Er kann also nie mehr gewähren, als die Person selbst gerade darf.
#Warum es zwei Arten gibt
Anfangs war jeder Key mandantenweit. Für Monitoring-Agents und CI-Jobs passt das. Für Keys, die die Automatisierung einer Person abbilden, entstehen daraus zwei bekannte Probleme:
- Geist-Berechtigungen — jemand verlässt das Unternehmen, das Konto wird deaktiviert. Der persönliche API-Key läuft trotzdem weiter, bis ihn jemand von Hand widerruft. Genau dieser Widerruf wird beim Offboarding gern übersehen
- Veraltete Momentaufnahmen — ein Key wurde mit Schreibrecht angelegt. Monate später wurde die Person auf Lesezugriff zurückgestuft — der Key schreibt weiterhin
Nutzergebundene Keys lösen beides, weil sie die Berechtigungen live auswerten statt sie einzufrieren.
#Wie die Schnittmenge entsteht
Bei jedem Request prüft Uslimato in dieser Reihenfolge:
- Ist das Konto der Eigentümerin oder des Eigentümers aktiv? Wenn nein, endet der Request hier
- Welche Berechtigungen hat diese Person aktuell?
- Diese Berechtigungen werden auf API-Scopes abgebildet
- Der wirksame Scope ist die Schnittmenge aus den Scopes des Keys und den aufgelösten Scopes der Person
Fehlt der benötigte Scope in der Schnittmenge, antwortet die API mit 403 INSUFFICIENT_SCOPE.
#Abbildung von Berechtigungen auf Scopes
| Berechtigung | Ergibt die API-Scopes |
|---|---|
admin | Alle Scopes |
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 |
#Wie schnell Änderungen wirken
Berechtigungen werden bis zu 60 Sekunden zwischengespeichert. Ändert sich eine Gruppenmitgliedschaft oder eine Gruppenberechtigung, wird der Zwischenspeicher sofort erneuert — der Entzug wirkt dann beim nächsten Request.
#Wer welchen Key anlegen darf
Der Scope-Typ hat keinen Standardwert — er muss beim Anlegen immer ausdrücklich gewählt werden.
| Wer legt an | Typ | Für wen | Ergebnis |
|---|---|---|---|
| Beliebig | *nicht angegeben* | — | 400 SCOPE_REQUIRED |
| Administration | global | — | Angelegt |
| Administration | global | eine Person | 400 VALIDATION_ERROR |
| Ohne Adminrecht | global | — | 403 GLOBAL_KEY_ADMIN_ONLY |
| Administration | nutzergebunden | Mitglied des Mandanten | Angelegt |
| Administration | nutzergebunden | Person aus fremdem Mandanten | 400 INVALID_USER |
| Ohne Adminrecht | nutzergebunden | sich selbst | Angelegt |
| Ohne Adminrecht | nutzergebunden | jemand anderen | 403 FORBIDDEN |
Ob Personen ohne Adminrecht überhaupt eigene Keys anlegen dürfen, steuert eine Einstellung pro Mandant — siehe Admin-Modus.
#Was mit einem Key passiert
| Ereignis | Wirkung auf einen nutzergebundenen Key |
|---|---|
| Person aus einer Gruppe entfernt | Wirksamer Scope schrumpft innerhalb von 60 Sekunden |
| Konto deaktiviert | Der nächste Request wird abgelehnt |
| Konto gelöscht | Der Key wird automatisch entfernt |
| Key ausdrücklich widerrufen | Der Key ist sofort deaktiviert |
#Welchen Typ wann
Global, wenn der Key einen Dienst darstellt und keine Person — CI, Backups, Monitoring —, wenn er weiterlaufen soll, auch wenn jemand geht, oder wenn die Integration bewusst einen breiten, rollenunabhängigen Zugriff braucht.
Nutzergebunden, wenn der Key die Automatisierung einer Person ist, wenn er Rollenwechseln automatisch folgen soll, oder wenn ein Offboarding den Key ohne Zusatzschritt mit erledigen soll.