Wissensdatenbank

API-Schlüssel

Ein Schlüssel pro Aufgabe, beschränkt auf die Scopes und Absender, die er braucht, und jeder Aufruf protokolliert.

Details

Erstellt unter Einstellungen → API-Schlüssel in einem Workspace, der Ihnen gehört. Das Secret wird einmal angezeigt, und jeder Schlüssel ist ein oe_live_-Schlüssel.
Ein Schlüssel hält nur die gewählten Scopes, ein neuer beginnt mit emails:send. Er kann auch eine Rolle tragen, die eine Obergrenze ist und keine zweite Berechtigung: GET /ping liefert die Scopes, die der Schlüssel nennt, und die, die ihm die Rolle lässt, sodass eine 403 für einen Scope, den der Schlüssel offensichtlich hat, eine sichtbare Ursache hat.
Der Sendebereich nennt bis zu 25 ganze Domains und 50 einzelne Adressen. Eine ganze Domain deckt auch später hinzugefügte Adressen ab, und ein Absender außerhalb der Liste wird mit 403 abgelehnt.
Ein optionales Ablaufdatum lässt einen Schlüssel von selbst auslaufen, bis zu zehn Jahre im Voraus.
Rotieren tauscht nur das Secret: ID, Scopes, Sendebereich und Anfrageverlauf bleiben, und das alte Secret hört auf zu funktionieren, sobald das neue erstellt ist. Ein Schlüssel mit keys:write kann sich über die API selbst rotieren. Widerrufen ist ein Update und kein Löschen, sodass ein späterer Aufruf revoked_api_key erhält.
Jeder authentifizierte Aufruf wird mit Methode, Pfad, Status, Fehlercode, Dauer, IP und User-Agent protokolliert, nie mit Body oder Query-String. Die Schlüsselseite zeigt das als Analytics, Aktivität und Anfragen, mit den meistgenutzten Routen, wie oft sie scheitern und ihrer mittleren Latenz, und dieselben Ansichten decken mehrere Schlüssel auf einmal ab. Das Protokoll wird behalten, nicht gekürzt.
Alles, was die Seite kann, geht auch über die API und das SDK: GET /keys und GET /keys/{id} lesen Schlüssel ohne ihre Secrets, POST /keys erzeugt einen, PATCH /keys/{id} benennt ihn um, ändert seine Scopes oder seinen Sendebereich und schaltet ihn aus und wieder ein, und rotate, revoke und delete tun, was sie sagen. Anfrageprotokoll und Aktivität lesen sich genauso, für einen Schlüssel oder für alle, mit den Filtern der Seite. Lesen braucht keys:read und jede Änderung keys:manage, zwei Scopes, die kein Schlüssel hat, solange sie ihm niemand gegeben hat. Der MCP-Server liest Protokoll und Aktivität ebenfalls, als listApiKeyRequests und listApiKeyActivity.
Ein Schlüssel erzeugt oder erreicht nie einen Schlüssel, der weiter reicht als er selbst: Scopes, Rolle, Ablauf, Modus und Sendebereich müssen alle innerhalb des aufrufenden Schlüssels liegen. Die erneute Bestätigung, die die Konsole verlangt, kann bei einem Aufruf mit einem Schlüssel nicht greifen, also ist keys:manage ein Zugang, der Zugänge erzeugt. Geben Sie ihn nur einer Automatisierung, die Schlüssel ausstellt, mit eigener Rolle, eigenem Sendebereich und eigenem Ablauf, und behalten Sie den Aktivitäts-Tab im Blick, wo alles, was sie tut, auf sie verbucht wird.
Was fehlt: Ein Schlüssel lässt sich nicht an IP-Adressen binden, und es kann kein Testmodus-Schlüssel erzeugt werden.