Ein geplanter Versand sollte weiter funktionieren, wenn die Person, die ihn eingerichtet hat, das Unternehmen verlässt. Ein Tool, das für diese Person handelt, braucht stattdessen Zugriff, der deren Berechtigungen folgt.
Wählen Sie die Zugangsdaten anhand dieser Eigentümerschaft. Halten Sie beide Arten von Zugangsdaten aus Browser-Code und Logs heraus, weil jeder, der sie besitzt, authentifizierte Anfragen senden kann.
Was kann ich mit den einzelnen Zugangsdaten tun?
Ein API-Key handelt für einen Workspace. Ein OAuth-Token ermöglicht einem autorisierten Tool, für eine Person zu handeln.
Bird API-Keys beginnen mit bk_. Ihre Berechtigungen gehören zum Workspace, sodass das Entfernen des Erstellers sie nicht ungültig macht. Vergeben Sie nur die Scopes, die der Service benötigt, um den Schaden durch einen exponierten Key zu begrenzen.
Ein Key kann keine Operationen auf Organisationsebene ausführen, etwa das Verwalten von Organisationsmitgliedern oder der Abrechnung. Mehr Workspace-Scopes hinzuzufügen entfernt diese Grenze nicht.
Wenn Sie sich über den CLI- oder MCP-Server anmelden, autorisieren Sie ein Tool mit einer Teilmenge Ihrer Berechtigungen. Das Tool erhält ein kurzlebiges bt_-Token. Es verwaltet die Token-Erneuerung selbst – kopieren Sie dieses Token also nicht in den Secret Manager eines Services.
Widerrufen Sie ein autorisiertes Tool über Profile > Connected apps. Verwenden Sie Authentifizierung, um Scopes auszuwählen und Workspace-Keys von persönlichen Grants zu unterscheiden.
Wie rotiere ich einen API-Key?
Stellen Sie einen Ersatz aus und deployen Sie ihn, bevor die Überlappung des alten Keys endet.
Sie können über das Dashboard rotieren, mit bird api-keys rotate oder über das api_keys_rotate MCP-Tool. CLI- und MCP-Rotation erfordern einen persönlichen Grant mit api_keys:write. Ein API-Key kann diese Berechtigung nicht besitzen und keinen anderen Key rotieren.
Die Rotation gibt das token des Ersatzes nur einmal zurück. Speichern Sie es sofort, weil spätere Abfragen es nicht wiederherstellen können. Der Ersatz behält den alten Namen und die IP-Einschränkungen. Er behält auch die Berechtigungen, es sei denn, Sie liefern neue scopes.
Setzen Sie grace_period, um die Überlappung zu steuern. Der Standardwert ist 24h – schließen Sie das Deployment also innerhalb dieses Tages ab. Ein früherer Ablauf des alten Keys gilt weiterhin. Die Rotation verlängert ihn nie.
Verwenden Sie grace_period: "0", wenn ein geleakter Key sofort widerrufen werden soll. Gecachte Validierung kann ihn kurzzeitig noch akzeptieren, wie unten beschrieben.
- Fordern Sie die Rotation an und speichern Sie das zurückgegebene Token.
- Deployen Sie den Ersatz in jedem Service, bevor die Überlappung endet.
- Bestätigen Sie erfolgreiche Anfragen mit dem Ersatz anhand der Service-Logs.
- Lassen Sie den alten Key ablaufen oder widerrufen Sie ihn, wenn die Umstellung abgeschlossen ist.
Die Rotationsreferenz beschreibt den Befehl und seine Optionen.
Was kann bei der Rotation schiefgehen?
Eine verlorene Antwort kann dazu führen, dass Sie einen ausgestellten Ersatz haben, dessen Token Sie nie gespeichert haben.
Verwenden Sie denselben Idempotency-Key, wenn Sie die Rotationsanfrage erneut versuchen, damit Bird die Antwort wiedergeben kann. Ein Key kann nur einmal rotiert werden. Ohne denselben Idempotenz-Key gibt eine wiederholte Rotation 409 zurück. Rotieren Sie den Ersatz für eine spätere geplante Änderung.
Ein widerrufener Key kann nicht rotiert werden. Erstellen Sie einen neuen Key, wenn der ursprüngliche bereits widerrufen ist.
Der Ersatz hat keinen Ablauf, auch wenn der ursprüngliche Key einen hatte. Sie können nachträglich keinen Ablauf hinzufügen. Erstellen Sie einen neuen Key mit expires_at, wenn er zu einem bestimmten Zeitpunkt aufhören soll zu funktionieren.
Erstellen Sie bei einem Deployment mit ungewisser Dauer einen zweiten Key und verwalten Sie die Überlappung selbst. Deployen Sie ihn, bevor Sie den ursprünglichen widerrufen. Die Übergangsfrist einer Rotation kann nach der Anfrage nicht verlängert werden.
Wie schnell wird ein Widerruf wirksam?
Ein widerrufener Key kann bis zu fünf Sekunden lang akzeptiert bleiben, während die gecachte Validierung abläuft.
Behandeln Sie einen exponierten Key während dieses Fensters als nutzbar. Der Widerruf ist dauerhaft – ein widerrufener Key kann nicht reaktiviert werden. Bird bewahrt den Eintrag für Audits auf.
Verwenden Sie key_prefix oder fingerprint, um einen Key in Support-Gesprächen zu identifizieren. Geben Sie nie die vollständigen Zugangsdaten an, weil diese Identifikatoren ausreichen, um den Key zu unterscheiden, ohne Zugriff zu gewähren.
Welche Zugangsdaten sollte ich wählen?
Wählen Sie danach, wem die Arbeitslast gehört und welche Berechtigungen sie benötigt.
- API-Key: ein Service, der unabhängig von seinem Ersteller weiter funktionieren soll.
- OAuth-Grant: ein CLI oder Agent, der innerhalb der Berechtigungen einer Person handelt.
- Rotation: ein Ersatz-Key, den Sie während einer bekannten Überlappung deployen können.
- Neuer Key mit Ablauf: Zugangsdaten, die zu einem bestimmten Zeitpunkt aufhören sollen zu funktionieren.
Kurz gesagt
Service-Zugangsdaten gehören zum Workspace.
Ein Key überlebt das Ausscheiden seines Erstellers. Ein Tool, das OAuth verwendet, handelt innerhalb der Berechtigungen der Person, die es autorisiert hat.
Deployen Sie während der Rotationsüberlappung.
Der alte Key funktioniert standardmäßig noch 24 Stunden, es sei denn, sein bestehender Ablauf greift früher.
Speichern Sie den Ersatz, sobald er ausgegeben wird.
Die Rotation gibt das neue Token nur einmal zurück. Verwenden Sie denselben Idempotenz-Key, wenn Sie die Rotationsanfrage erneut versuchen.
Widerruf hat ein kurzes Propagierungsfenster.
Gecachte Validierung kann einen widerrufenen Key bis zu fünf Sekunden lang akzeptieren – berücksichtigen Sie diese Verzögerung nach einem Leak.