Schlüsselverwaltung

Wie eine Integration an einen API-Key kommt, wie sie ihn rotiert, was bei Verlust zu tun ist — und warum du als Integrator einen Teil davon nicht selbst erledigen kannst.

Die Verwaltung ist nicht Teil der externen API

Keys, Freigaben und Mandanten-Policies werden ausschließlich in der Plattform-Oberfläche verwaltet (Endpunkte /api/user/api-keys und /api/admin/api-access — nur mit angemeldetem Benutzerkonto der Oberfläche erreichbar). Ein API-Key kommt dort per Design nicht hinein: die Key-Chain matcht nur /api/external/v1/**. Ein Key kann sich also weder selbst verlängern noch weitere Keys erzeugen.

Die drei Ebenen

Ebene	Wer richtet sie ein	Was sie festlegt
Mandanten-Policy	Operator/Admin	Ob der Mandant überhaupt API-Zugriff hat, welche Scopes maximal möglich sind, ob Personen sich selbst Keys ausstellen dürfen, sowie die Grenzwerte für Laufzeit, Anzahl und Rotationsfrist
Grant (Freigabe)	Operator/Admin, für eine konkrete Person	Für welchen Mandanten diese Person Keys erzeugen darf, mit welchen Scopes, bis wann, wie viele gleichzeitig
API-Key	die Person selbst, im Einstellungsdialog	Anzeigename, Scopes (Teilmenge des Grants), Laufzeit (feste Stufe)

Wirksam ist immer die Schnittmenge: Key ∩ Grant ∩ Policy. Wird oben etwas entzogen, verliert der Key es sofort — ohne dass jemand den Key anfasst. Was aktuell wirkt, sagt dir GET /api/external/v1/me.

Der Weg zu einem Key

1. Mandanten freischalten lassen. Der Betreiber legt für den Standort-Root (z. B. musterhaus) eine Policy an und wählt die maximal erlaubten Scopes.
2. Freigabe für eine Person beantragen. Ein Grant hängt immer an einem echten Benutzerkonto — nicht an einer Rolle, nicht an einem technischen Konto. Diese Person muss Mitglied des Mandanten sein und aktiv bleiben. Der Antrag sollte Zweck, Scopes und eine Ticket-Referenz nennen; beides wird im Audit-Trail festgehalten.
3. Key erzeugen. Die Person öffnet ihre Einstellungen, wählt den Mandanten, vergibt einen sprechenden Anzeigenamen (z. B. „j-lawyer Produktion") und wählt die Scopes aus dem, was der Grant hergibt.
4. Key genau einmal abgreifen. Der Klartext-Key wird einmalig angezeigt und ist danach nicht wiederherstellbar. Er gehört sofort in den Secret-Store deiner Integration — nicht in ein Ticket, nicht in ein Chat-Fenster, nicht ins Repository.
5. Smoke-Test. GET /api/external/v1/me bestätigt Key, Mandant und effektive Scopes.

Wen wählt man als Grant-Person?

Der Key sieht nie mehr als die Person dahinter: die fachlichen Abfragen scopen weiterhin auf deren Standort-Mitgliedschaften, und ihre Rechte entscheiden, ob ein Fall abgeschlossen oder wiedereröffnet werden darf. Nimm also keine zufällige Person, sondern eine mit genau dem Zuschnitt, den die Integration braucht — und plane, dass ihr Ausscheiden alle ihre Keys tötet.

Grenzwerte

Die Werte sind Teil der Policy und pro Mandant einstellbar. Die Voreinstellungen:

Grenze	Voreinstellung	Bedeutung
Standard-Laufzeit eines Keys	90 Tage	wenn beim Erzeugen keine Stufe gewählt wird, gilt die größte Stufe, die hineinpasst
Maximale Laufzeit	365 Tage	längere Stufen stehen nicht zur Wahl — begrenzt die Länge einer Stufe, nicht die Zahl der Verlängerungen
Gleichzeitig nutzbare Keys je Person und Mandant	2	ein Vorgänger in der Rotationsfrist zählt mit
Standard-Rotationsfrist	120 Minuten	Übergangszeit, in der der alte Key noch funktioniert
Maximale Rotationsfrist	1440 Minuten (24 h)	mehr wird auf diesen Wert gekappt

Die Laufzeit ist kein freies Datum, sondern eine feste Stufe: 1, 3, 6 oder 12 Monate (gerechnet als 30 / 90 / 180 / 365 Tage). Ein Key läuft ab, ohne dass jemand etwas tut: Nach dem Ablaufdatum antwortet jeder Request mit 401 API_KEY_INVALID. Damit das nicht unbemerkt passiert, bekommt die Inhaber_in des Keys 14, 7 und 1 Tag vorher eine Mail — und eine weitere, sobald der Key abgelaufen ist. Diese Mails sind Betriebsmails und lassen sich nicht über die Benachrichtigungseinstellungen abschalten.

Verlängern statt ersetzen

Ein Key muss zum Ablauf nicht ersetzt werden: Solange er noch läuft, kann die Inhaber_in ihn in ihren Einstellungen verlängern. Das Secret bleibt dabei unverändert — deine Integration merkt davon nichts.

• Verlängern setzt das Ablaufdatum auf heute + Laufzeit. Das Fenster rollt bei jeder Verlängerung neu; eine Gesamtobergrenze gibt es nicht — ein gepflegter Key läuft beliebig lange.
• Beim Verlängern darf die Stufe gewechselt werden (z. B. von 3 auf 12 Monate). Das ist auch der Ausweg, wenn die Restlaufzeit noch länger ist als die bisherige Stufe: eine Verlängerung zieht den Ablauf nie nach vorn, mit derselben Stufe wäre sie dann wirkungslos und wird abgelehnt.
• Möglich nur aus ACTIVE oder DISABLED und nur, solange der Key noch nicht abgelaufen ist. Ein abgelaufener Key braucht einen Nachfolger; ein Vorgänger in der Rotationsfrist wird nie verlängert.
• Jede Verlängerung setzt die Ablauf-Vorwarnung zurück (die 14/7/1-Mails kommen für den neuen Termin erneut) und landet als KEY_EXPIRY_CHANGED mit altem und neuem Datum im Audit-Trail.
• Auch der Betreiber kann verlängern (mit Begründung, fürs Audit) — das ist der einzige Eingriff, den er an einem Key vornehmen kann, ohne ein Secret zu erzeugen. Erstellen und Rotieren bleiben allein bei der Inhaber_in.

Verlängern hält den Key am Leben, Rotation wechselt das Secret. Wer nur die Laufzeit braucht, verlängert; wer das Secret aus der Hand geben musste oder turnusmäßig wechseln will, rotiert.

Rotation mit Übergangsfrist

Rotation heißt: ein neuer Key entsteht, der alte geht in eine Übergangsfrist (ROTATION_GRACE) und bleibt bis zu deren Ende gültig. So kannst du deployen, ohne eine Minute Ausfall.

Der Ablauf aus Integrator-Sicht:

1. Rotation in der Oberfläche auslösen und die gewünschte Übergangsfrist wählen (0 bis zum Maximum; 0 bedeutet: der alte Key ist sofort tot).
2. Den neuen Key im Secret-Store hinterlegen und ausrollen.
3. Mit GET /me prüfen, dass die Instanzen den neuen Key nutzen — die publicId in der Antwort sagt dir, welcher Key gerade spricht.
4. Die Übergangsfrist vorzeitig beenden, sobald alles läuft (der alte Key wird dann widerrufen).

Randbedingungen:

• Es kann nur eine Rotation gleichzeitig laufen: solange ein Vorgänger in der Übergangsfrist ist, wird eine weitere Rotation abgelehnt.
• Der Vorgänger stirbt automatisch am Ende der Frist — ein Nachlaufen ist nicht möglich, und die Frist lässt sich nicht verlängern.
• Ein rotierter Key wird nie wiederbelebt: Widerruf ist endgültig.
• Die Scopes des Nachfolgers werden erneut gegen Grant und Policy geschnitten — hat sich dort etwas geändert, kann der neue Key weniger können als der alte. Prüfe nach jeder Rotation GET /me.

Empfehlung: behandle Rotation als normalen Betriebsvorgang — nicht als Notfallmaßnahme — und übe den Deploy-Weg, bevor du ihn brauchst. Gegen das bloße Ablaufen genügt die Verlängerung.

Weitere Lebenszyklus-Zustände

Zustand	Was er bedeutet	Umkehrbar?
ACTIVE	normal nutzbar	—
ROTATION_GRACE	Vorgänger einer Rotation, bis graceEndsAt noch nutzbar	endet automatisch
DISABLED	vorübergehend stillgelegt (z. B. während einer Untersuchung)	ja, wieder aktivierbar
REVOKED	endgültig widerrufen	nein
COMPROMISED	wegen eines Vorfalls widerrufen, ohne Übergangsfrist	nein

Alle vier Zustände außer ACTIVE/ROTATION_GRACE führen bei jedem Request zu 401 API_KEY_INVALID — ununterscheidbar von „Key existiert nicht". Wenn deine Integration plötzlich 401 sieht, ist der Blick in die Verwaltungsoberfläche der schnellste Weg zur Ursache.

Der Grant hat einen eigenen Lebenszyklus: ACTIVE, SUSPENDED (vorübergehend ausgesetzt) und REVOKED (endgültig; eine erneute Freigabe erzeugt immer einen neuen Grant, alte Keys bleiben tot). Ein ausgesetzter oder widerrufener Grant legt sofort alle Keys darunter still.

Bei Kompromittierung

Ein Key gilt als kompromittiert, sobald er irgendwo gelandet ist, wo er nicht hingehört: im Repository, im Log, im Ticket, im Screenshot, auf einem verlorenen Laptop.

1. Sofort als kompromittiert widerrufen — nicht „deaktivieren", nicht „rotieren mit Frist". Der Incident-Widerruf beendet den Zugang ohne Übergangszeit und ist endgültig. Im Zweifel: alle Keys der Person bzw. des Mandanten auf einen Schlag widerrufen.
2. Neuen Key ausstellen und ausrollen. Die Ausfallzeit ist der Preis der Sicherheit — deshalb ist ein zweiter, ungenutzter Reserve-Key selten sinnvoll (er verdoppelt nur die Angriffsfläche); besser ist ein schneller, geübter Deploy-Weg.
3. Spur suchen. Jede Erstellung, Rotation, Deaktivierung und jeder Widerruf landet mit Akteur, Zeitpunkt und Begründung im Audit-Trail des Grants; fehlgeschlagene Authentifizierungen werden ebenfalls protokolliert. Der last_used_at-Zeitstempel des Keys zeigt, ob er überhaupt benutzt wurde. Der Betreiber kann daraus rekonstruieren, was mit dem Key passiert ist — nenn ihm die publicId.
4. Betreiber informieren, auch wenn du selbst schon widerrufen hast: nur er sieht den vollständigen Audit-Trail und kann beurteilen, ob weitere Mandanten betroffen sind.

Die publicId (der mittlere Block des Keys) ist nicht geheim und darf im Ticket stehen — sie identifiziert den Key eindeutig. Das Secret nie.

Betriebshygiene

• Ein Key pro Umgebung und Zweck. Die Umgebung steckt im Key-Namen (usp_dev_…, usp_prod_…), aber ein sprechender Anzeigename erspart im Zweifel die Rätselei.
• Scopes minimal. Kein attachments:write für eine Integration, die nur liest; kein reference-data:write, wenn niemand den Versicherungskatalog pflegt — dieser Scope wirkt ohnehin nur an einem Operator-Konto.
• Nie im Repository, nie im Log. Der Key ist ein Bearer-Credential: wer ihn hat, ist du. Prüfe auch, dass dein HTTP-Client keine Header mitloggt.
• Immer TLS. Ohne verschlüsselte Verbindung ist der Key auf der Leitung lesbar.
• GET /me beim Start deiner Anwendung. Ein früher, klarer Fehler beim Hochfahren ist besser als ein 401 mitten im Sync-Lauf.
• 401 alarmiert, 429 wartet. Siehe Fehlercodes.

Verwandte Seiten

• Authentifizierung und Scopes — Key-Format, Header, Scope-Katalog, Rate-Limits.
• Integrator-Kochbuch — die Sync-Schleife in konkreten Aufrufen.