Authenticatie
Elk API-verzoek authenticeert met een API-sleutel die als bearer-token in de Authorization-header wordt meegegeven:
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 Platform tools > API keys, of zonder browser met bird api-keys create. Deze pagina beschrijft het contract op protocolniveau.
Sleutelformaat
Een sleutel begint met bk_{region}_, dat de regio aangeeft waar de sleutel is aangemaakt. bk_us1_-sleutels zijn alleen geldig bij https://us1.platform.bird.com, en bk_eu1_-sleutels alleen bij https://eu1.platform.bird.com. Officiële SDK's en de CLI gebruiken dit prefix om de host te kiezen.
De volledige sleutel wordt precies één keer geretourneerd, in het antwoord waarmee je hem aanmaakt. De platte tekst kun je daarna niet meer ophalen, en het dashboard toont alleen een kort key_prefix (de eerste 15 tekens). Ben je een sleutel kwijt, trek hem dan in en vervang hem.
Foutantwoorden
Alle fouten gebruiken het standaard foutantwoord.
| Status | Wanneer |
|---|---|
401 | De Authorization-header ontbreekt, de sleutel is ongeldig of onbekend, of de sleutel is ingetrokken. |
403 | De sleutel is geldig maar mist de scope die het endpoint vereist. |
421 | De 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
- Authenticatie- & API-sleutelgids: sleutels aanmaken, scopen, roteren en intrekken
- Basis-URL's en regio's: regionale hosts en het regiomodel
- Fouten: het foutantwoord en de catalogus
Gerelateerde bronnen
Ga verder met de documentatie, handleidingen en voorbeelden voor dit onderwerp.