Authentication
Every API request authenticates with an API key passed as a bearer token in the Authorization header:
curl https://us1.platform.bird.com/v1/email/messages \
-H "Authorization: Bearer bk_us1_Ab3xKq9mP2wR5tY8uI1oL4nJ..."Keys are workspace-scoped: a key authenticates as your workspace, carries the scopes chosen at creation, and can reach only its resources. How to create, scope, rotate, and revoke keys is covered in the Authentication & API keys guide: create them in the dashboard under Platform tools > API keys, or without a browser with bird api-keys create. This page covers the wire-level contract.
Key format
A key starts with bk_{region}_, naming the region where it was created. bk_us1_ keys are valid only against https://us1.platform.bird.com, and bk_eu1_ keys only against https://eu1.platform.bird.com. Official SDKs and the CLI use this prefix to pick the host.
The full key is returned exactly once, in the response that creates it. The plaintext cannot be retrieved again, and the dashboard shows only a short key_prefix (the first 15 characters). Revoke and replace a lost key.
Failure responses
All failures use the standard error envelope.
| Status | When |
|---|---|
401 | The Authorization header is missing, the key is malformed or unknown, or the key has been revoked. |
403 | The key is valid but lacks the scope the endpoint requires. |
421 | The key's region does not match the host, such as a bk_eu1_... key sent to us1.platform.bird.com. |
The 421 Misdirected Request body (error type misdirected_error, code E01010) names the correct regional host, so a client can detect the mistake and re-send without guesswork. See Base URLs and regions.
Dashboard sessions are not API keys
The Bird dashboard does not use API keys: a person logging in gets a session cookie, scoped to their own user permissions. Session cookies are not accepted on the programmatic API surface, and API keys are not accepted by the dashboard. Server workloads always use API keys.
Related
- Authentication & API keys guide: creating, scoping, rotating, and revoking keys
- Base URLs and regions: regional hosts and the region model
- Errors: the error envelope and catalog
Related resources
Continue with the documentation, guides and examples for this topic.