API-Schlüssel
Ein API-Schlüssel gibt einem anderen Programm Zugang: Lohnsoftware, Projektsystem, ein eigenes Skript. Er wird einmal angezeigt und danach nie wieder.
Zu finden unter API. Nötig ist api:read zum Ansehen, api:create zum Ausstellen, api:delete zum Widerrufen.
Aufbau und Speicherung
Der Schlüssel hat die Form wt_<8 Zeichen>.<Rest>. Gespeichert wird nur ein SHA-256-Hash über beide Teile zusammen; der Präfix steht daneben, damit sich der Eintrag beim Prüfen finden lässt.
Der Schlüssel selbst steht nirgends in der Datenbank. Geht er verloren, lässt er sich nicht wiederherstellen — es bleibt nur, einen neuen auszustellen und den alten zu widerrufen.
Benutzen
Im Kopffeld X-API-Key:
curl https://zeit.example.de/api/v1/time-entries \
-H "X-API-Key: wt_1a2b3c4d.e5f6..."Kein Bearer-Token, keine Anmeldung, kein Erneuerungs-Cookie. Siehe Authentifizierung.
Geltungsbereiche
Ein Schlüssel trägt eine Liste von Rechten. Der Wächter richtet sich beim Zugriff allein nach ihnen und nicht nach der Rolle des ausstellenden Benutzers.
Deshalb wird beim Ausstellen geprüft:
- Gibt es den Bereich? Ein Tippfehler ergäbe sonst einen Schlüssel, der stillschweigend nichts kann.
- Hat der Ausstellende ihn selbst? Sonst genügte das Recht, Schlüssel auszustellen, um sich jedes andere zu verschaffen.
Geben Sie nur, was gebraucht wird. Eine Lohnschnittstelle, die Zeiten ausliest, braucht time_entry:read und report:export — nicht time_entry:approve.
Wann ein Schlüssel nicht mehr gilt
| Grund | Meldung |
|---|---|
| unbekannter Präfix | API-Schlüssel unbekannt. |
| falscher Hash | API-Schlüssel ungültig. |
| widerrufen | API-Schlüssel wurde widerrufen. |
| Ablaufdatum überschritten | API-Schlüssel ist abgelaufen. |
| ausstellendes Konto gesperrt | Das zugehörige Benutzerkonto ist nicht aktiv. |
Der letzte Punkt ist wichtig für den Austritt eines Mitarbeiters: Wird sein Konto gesperrt, enden auch die Schlüssel, die er ausgestellt hat.
Ablaufdatum
Ein Schlüssel darf eines tragen. Ohne Datum gilt er, bis ihn jemand widerruft — was für einen dauerhaft eingerichteten Anschluss richtig ist und für ein einmaliges Skript nicht.
Was festgehalten wird
Am Schlüssel steht, wann er zuletzt benutzt wurde. Der Zeitstempel wird nur gelegentlich geschrieben: Er dient der Übersicht, nicht der Abrechnung, und soll nicht jede Anfrage um einen Schreibvorgang verlängern.
Ausstellen und Widerrufen stehen im Prüfprotokoll.