API-Key-Verwaltung
Ein API-Key ist ein Anwendungs-Credential. Er gehört zu Ihrem Workspace, und eine Anwendung, die ihn besitzt, kann die Bird API innerhalb der zugewiesenen Scopes aufrufen. Sie können Keys im Dashboard oder über die API verwalten. Den vollständigen technischen Vertrag finden Sie unter Authentication & API-Keys.
Wo sich Keys befinden
Öffnen Sie API-Keys, angeheftet am unteren Ende der Seitenleiste neben Webhooks und Logs. Die Seite listet Name, maskiertes Präfix, Scopes, Status, Ablaufdatum und Datum der letzten Nutzung jedes Keys auf.
Zum Erstellen, Bearbeiten und Widerrufen von Keys benötigen Sie die passende Workspace-Rolle: Admins und Developers verfügen darüber. Siehe Users, teams & roles.
Einen Key erstellen
- Wählen Sie auf der API-Keys-Seite die Option, einen neuen Key zu erstellen.
- Benennen Sie ihn nach seinem Zweck, z. B. "Billing service production,", nicht nach einer Person.
- Wählen Sie Scopes. Jeder Scope hat eine read- oder write-Stufe. Vergeben Sie nur die Scopes und Stufen, die die Anwendung benötigt.
- Erstellen Sie den Key und kopieren Sie das Secret sofort.
Das Secret wird nur einmal angezeigt
Der vollständige Key erscheint einmal, beim Erstellen oder Rotieren des Keys. Bird kann das Secret nicht erneut anzeigen. Kopieren Sie es direkt in einen Secret-Manager oder eine Deployment-Konfiguration. Falls Sie es verlieren, rotieren oder ersetzen Sie den Key.
Bearbeiten Sie die Scopes eines Keys über seine Zeile auf der API-Keys-Seite. Die Bearbeitung ersetzt den Berechtigungssatz und behält dasselbe Secret bei. Möglicherweise müssen Sie einen älteren Key rotieren, um eine Berechtigung hinzuzufügen. Siehe Authentication & API-Keys für Scope-Einschränkungen.
Einen Key widerrufen
Widerrufen Sie einen Key, wenn er nicht mehr benötigt wird oder Sie vermuten, dass er kompromittiert wurde. Ein Widerruf ist endgültig. Die Key-Validierung nutzt einen kurzlebigen Cache, sodass ein widerrufener Key bis zu fünf Sekunden lang weiter funktionieren kann, bevor Anfragen die Authentifizierung nicht bestehen.
Wenn Sie vermuten, dass ein Key kompromittiert wurde, widerrufen Sie ihn und stellen Sie einen Ersatz bereit. Anfragen schlagen fehl, bis die Anwendung einen aktiven Key verwendet.
Um ohne Ausfallzeit zu rotieren, verwenden Sie die Rotationsaktion und behalten Sie die standardmäßige 24-Stunden-Übergangsfrist bei. Stellen Sie den Ersatz bereit, bevor die Übergangsfrist endet. Verkürzen Sie die Übergangsfrist nur, wenn Sie Aufrufer schneller aktualisieren können.
Alles wird protokolliert
Key-Erstellung, Scope-Bearbeitungen, Rotation und Widerruf erscheinen im Audit-Log Ihrer Organisation. Eine Scope-Bearbeitung protokolliert die hinzugefügten und entfernten Scopes. Blenden Sie widerrufene Keys in der Key-Liste ein, um deren Metadaten zu prüfen.
Gute Gewohnheiten
- Verwenden Sie einen Key pro Anwendung und Umgebung. Trennen Sie Staging- und Produktions-Keys, damit Sie einen widerrufen können, ohne den anderen zu beeinträchtigen.
- Beobachten Sie die Spalte „Zuletzt verwendet". Widerrufen Sie inaktive Keys, die nicht mehr benötigt werden.
- Speichern Sie Keys niemals in clientseitigem Code oder öffentlichen Repositories. Keys gehören ausschließlich in serverseitige Konfigurationen und Secret-Manager.
Nächste Schritte
- Authentication & API-Keys: Key-Aufbau, Scope-Details und der API-Vertrag
- Audit-Log: Key-Erstellungs- und Widerrufsereignisse prüfen
- Users, teams & roles: wer Keys verwalten kann
Verwandte Ressourcen
Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema. Die Ressourcen sind auf Englisch.