API-Schlüssel

GET /keys listet jeden Schlüssel, den der Aufrufer sehen kann, neueste zuerst und Seite für Seite, mit Status, Scopes, Rolle, Sendebereich, letzter Nutzung und wer ihn angelegt und zuletzt geändert hat. GET /keys/{id} liest einen. Kein Lesezugriff gibt je ein Secret zurück: maskedKey reicht, um zwei Schlüssel auseinanderzuhalten. Beide brauchen keys:read.

{  "object": "api_key",  "id": "4c1b257a66287fd113bd89d0",  "name": "Billing sender",  "maskedKey": "oe_live_4c1b…kX7a",  "status": "active",  "scopes": ["emails:send"],  "roleId": null,  "domainAllowlist": ["billing.acme.com"],  "expiresAt": "2026-12-22T09:00:00.000Z",  "lastUsedAt": "2026-09-23T08:14:02.000Z",  "createdBy": { "kind": "apiKey", "name": "API key Provisioner", "label": "API key Provisioner" }}

• —POST /keys erzeugt einen Schlüssel und gibt sein Secret einmal in token zurück. Ohne Angabe ist der Scope emails:send, und Rolle, Sendebereich und Ablauf sind die des Aufrufers.
• —PATCH /keys/{id} benennt einen Schlüssel um, ersetzt seine Scopes oder seinen Sendebereich und schaltet ihn mit enabled aus und ein. Ausschalten ist die umkehrbare Wahl: Der Schlüssel behält alles und wird mit inactive_api_key abgewiesen, bis er wieder eingeschaltet wird.
• —POST /keys/{id}/rotate gibt einem Schlüssel ein neues Secret und liefert es einmal zurück. Das alte Secret funktioniert ab dem Moment nicht mehr, in dem der Aufruf zurückkehrt.
• —POST /keys/{id}/revoke legt einen Schlüssel endgültig still, mit optionalem reason. DELETE /keys/{id} entfernt ihn danach aus der Liste und behält seinen Verlauf.
• —Jeder dieser Aufrufe braucht keys:manage. Den aufrufenden Schlüssel selbst zu rotieren geht auch mit keys:write, genau wie POST /keys/self/rotate.

Jede Änderung wird gegen den Schlüssel geprüft, der sie vornimmt. Ein Schlüssel, der auf irgendeiner Achse außerhalb des Aufrufers landen würde, wird mit 403 beyond_caller_authority abgewiesen, und param nennt die Achse:

• —Scopes: nur Scopes, die der Aufrufer hält, nachdem seine eigene Rolle sie eingegrenzt hat.
• —Rolle: Ein Aufrufer, den eine Rolle deckelt, kann nur Schlüssel mit derselben Rolle erstellen und verwalten.
• —Ablauf: Ein Aufrufer, der abläuft, kann nur Schlüssel erstellen und verwalten, die nicht später ablaufen.
• —Modus: Ein Testschlüssel erreicht nur Testschlüssel.
• —Sendebereich: nur Domains und Adressen innerhalb des eigenen Bereichs des Aufrufers, und eine einzelne Adresse deckt nie ihre ganze Domain ab.

Die Konsole verlangt eine erneute Bestätigung, bevor sie einen Schlüssel erzeugt oder rotiert. Ein Aufruf mit einem Schlüssel kann das nicht, also ist keys:manage ein Zugang, der Zugänge erzeugt: Ein geleakter Schlüssel damit kann eigene Schlüssel erzeugen, bis zu seiner eigenen Reichweite, die weiter funktionieren, nachdem er widerrufen wurde.

• —Geben Sie keys:manage nur einer Automatisierung, deren Aufgabe das Ausstellen von Schlüsseln ist, nie einem Schlüssel, der Mail sendet.
• —Grenzen Sie diesen Schlüssel ein: eine Rolle, ein Sendebereich und ein Ablauf. Alles, was er erzeugt, erbt alle drei und kann sie nie überschreiten.
• —Beobachten Sie GET /keys/activity. Jeder Schlüssel, den er erstellt, ändert oder widerruft, wird namentlich auf ihn verbucht, sodass ein Leck als Schlüssel sichtbar wird, die Sie nicht erwartet haben.
• —keys:read legt das Anfrageprotokoll offen, samt IP-Adressen und User-Agents. Behandeln Sie es wie Audit-Zugriff.

GET /keys/requests und GET /keys/{id}/requests lesen jeden authentifizierten Aufruf eines Schlüssels, neueste zuerst: Methode, Pfad, Status, Fehlercode, Dauer, IP und User-Agent, nie einen Body oder Query-String. keyIds, failedOnly, since und until sind die Filter der Konsole. GET /keys/activity und GET /keys/{id}/activity lesen, was mit Schlüsseln passiert ist, wobei actor nennt, wer es getan hat, als @username oder API key <name>. Nichts wird gelöscht, und ein gelöschter Schlüssel behält seinen Verlauf.