Authentifizierung

Jede API-Anfrage authentifiziert sich mit einem API-Schlüssel, der als Bearer-Token im Authorization-Header übergeben wird:

Codebeispiel

curl https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer bk_us1_Ab3xKq9mP2wR5tY8uI1oL4nJ..."

Schlüssel sind Workspace-bezogen: Ein Schlüssel authentifiziert sich als Ihr Workspace, trägt die bei der Erstellung gewählten Scopes und kann nur auf dessen Ressourcen zugreifen. Wie Sie Schlüssel erstellen, einschränken, rotieren und widerrufen, beschreibt der Leitfaden zu Authentifizierung und API-Schlüsseln: Erstellen Sie sie im Dashboard unter Developers > API keys oder ohne Browser mit bird api-keys create. Diese Seite behandelt den Vertrag auf Protokollebene.

Schlüsselformat

Codebeispiel

bk_us1_Ab3xKq9mP2wR5tY8uI1oL4nJ...
└┬┘└┬┘ └──────────┬──────────┘└┬┘
 │  │          payload      checksum
 │  └ region (routes the request)
 └ Bird key prefix

Ein Schlüssel ist bk_{region}_{payload}{checksum}:

bk_{region}_: Das Präfix identifiziert den Credential-Typ und die Region, in der der Schlüssel erstellt wurde. bk_us1_-Schlüssel sind nur gegen https://us1.platform.bird.com gültig, und bk_eu1_-Schlüssel nur gegen https://eu1.platform.bird.com. Offizielle SDKs und die CLI verwenden dieses Präfix, um den Host auszuwählen. Das feste bk_-Präfix ist bei GitHub Secret Scanning registriert, sodass ein in einem öffentlichen Repository geleakter Bird-Schlüssel erkannt und gemeldet wird.
Payload: Ein langer zufälliger String mit mindestens 128 Bit Entropie.
Checksum: Die letzten 6 Zeichen sind eine Prüfsumme des restlichen Schlüssels, sodass ein Client einen falsch eingegebenen oder abgeschnittenen Schlüssel lokal abweisen kann, bevor eine Anfrage gesendet wird.

Der vollständige Schlüssel wird genau einmal zurückgegeben, in der Antwort, die ihn erstellt. Der Klartext kann nicht erneut abgerufen werden, und das Dashboard zeigt nur einen kurzen key_prefix (die ersten 12 Zeichen). Widerrufen und ersetzen Sie einen verlorenen Schlüssel.

Fehlerantworten

Alle Fehler verwenden die standardmäßige Fehlerantwort.

Status	Wann
401	Der Authorization-Header fehlt, der Schlüssel ist fehlerhaft oder unbekannt, oder der Schlüssel wurde widerrufen.
403	Der Schlüssel ist gültig, hat aber nicht den Scope, den der Endpunkt erfordert.
421	Die Region des Schlüssels stimmt nicht mit dem Host überein, z. B. ein bk_eu1_...-Schlüssel, der an us1.platform.bird.com gesendet wird.

Der 421 Misdirected Request-Body (Fehlertyp misdirected_error, Code E01010) nennt den korrekten regionalen Host, sodass ein Client den Fehler erkennen und die Anfrage ohne Raten erneut senden kann. Siehe Basis-URLs und Regionen.

Dashboard-Sitzungen sind keine API-Schlüssel

Das Bird-Dashboard verwendet keine API-Schlüssel: Eine Person, die sich anmeldet, erhält ein Session-Cookie, das auf ihre eigenen Benutzerberechtigungen beschränkt ist. Session-Cookies werden auf der programmatischen API-Oberfläche nicht akzeptiert, und API-Schlüssel werden vom Dashboard nicht akzeptiert. Server-Workloads verwenden immer API-Schlüssel.

Weiterführend

Leitfaden zu Authentifizierung und API-Schlüsseln: Erstellen, Einschränken, Rotieren und Widerrufen von Schlüsseln
Basis-URLs und Regionen: regionale Hosts und das Regionsmodell
Fehler: die Fehlerantwort und der Fehlerkatalog

Authentifizierung

Schlüsselformat

Fehlerantworten

Dashboard-Sitzungen sind keine API-Schlüssel

Weiterführend

Verwandte Ressourcen