Sign inGet Started
Aan de slag
Gidsen
API Reference
SDK's
CLI
Kennisbank
Changelog

Authenticatie

Elk API-verzoek authenticeert met een API-sleutel die als bearer-token in de Authorization-header wordt meegegeven:
Codevoorbeeld
curl https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer bk_us1_Ab3xKq9mP2wR5tY8uI1oL4nJ..."
Sleutels zijn aan een werkruimte gekoppeld: een sleutel authenticeert als je werkruimte, draagt de scopes die bij het aanmaken zijn gekozen en heeft alleen toegang tot de bijbehorende resources. Hoe je sleutels aanmaakt, scoped, roteert en intrekt staat in de Authenticatie- & API-sleutelgids: maak ze aan in het dashboard onder Developers > API keys, of zonder browser met bird api-keys create. Deze pagina beschrijft het contract op protocolniveau.

Sleutelformaat

Codevoorbeeld
bk_us1_Ab3xKq9mP2wR5tY8uI1oL4nJ...
└┬┘└┬┘ └──────────┬──────────┘└┬┘
 │  │          payload      checksum
 │  └ region (routes the request)
 └ Bird key prefix
Een sleutel is bk_{region}_{payload}{checksum}:
  • bk_{region}_: Het prefix identificeert het type credential en de regio waar de sleutel is aangemaakt. bk_us1_-sleutels zijn alleen geldig tegen https://us1.platform.bird.com, en bk_eu1_-sleutels alleen tegen https://eu1.platform.bird.com. Officiële SDK's en de CLI gebruiken dit prefix om de host te kiezen. Het vaste bk_-prefix is geregistreerd bij GitHub secret scanning, zodat een Bird-sleutel die in een openbare repository lekt, wordt gedetecteerd en gemeld.
  • Payload: Een lange willekeurige string met 128+ bits aan entropie.
  • Checksum: De laatste 6 tekens zijn een checksum van de rest van de sleutel, waarmee een client een verkeerd getypte of afgekapte sleutel lokaal kan afwijzen voordat er een verzoek wordt gedaan.
De volledige sleutel wordt precies één keer geretourneerd, in het antwoord dat de sleutel aanmaakt. De platte tekst kan niet opnieuw worden opgehaald, en het dashboard toont alleen een kort key_prefix (de eerste 12 tekens). Trek een verloren sleutel in en vervang hem.

Foutantwoorden

Alle fouten gebruiken het standaard foutantwoord.
StatusWanneer
401De Authorization-header ontbreekt, de sleutel is ongeldig of onbekend, of de sleutel is ingetrokken.
403De sleutel is geldig maar mist de scope die het endpoint vereist.
421De regio van de sleutel komt niet overeen met de host, bijvoorbeeld een bk_eu1_...-sleutel verzonden naar us1.platform.bird.com.
De 421 Misdirected Request-body (fouttype misdirected_error, code E01010) noemt de juiste regionale host, zodat een client de fout kan detecteren en opnieuw kan verzenden zonder te gissen. Zie Basis-URL's en regio's.

Dashboardsessies zijn geen API-sleutels

Het Bird-dashboard gebruikt geen API-sleutels: een persoon die inlogt krijgt een sessiecookie, gekoppeld aan de eigen gebruikersrechten. Sessiecookies worden niet geaccepteerd op het programmatische API-oppervlak, en API-sleutels worden niet geaccepteerd door het dashboard. Serverworkloads gebruiken altijd API-sleutels.

Gerelateerd

Gerelateerde bronnen

Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.

Begrijp het conceptShould I use a Bird SDK or call the API directly?Volg het leerpadBuild your first integrationImplementatiegidsSend your first email
Ontvang een implementatieoverzicht