Authentication
Every API request authenticates with an API key passed as a bearer token in the Authorization header:
Codebeispiel
curl https://us1.platform.bird.com/v1/email/messages \
-H "Authorization: Bearer bk_us1_Ab3xKq9mP2wR5tY8uI1oL4nJ..."Keys are workspace-scoped: a key authenticates as its workspace, carries the scopes chosen at creation, and cannot reach resources in any other workspace. How to create, scope, rotate, and revoke keys is covered in the Authentication & API keys guide; this page covers the wire-level contract.
Key format
Codebeispiel
bk_us1_Ab3xKq9mP2wR5tY8uI1oL4nJ...
└┬┘└┬┘ └──────────┬──────────┘└┬┘
│ │ payload checksum
│ └ region (routes the request)
└ Bird key prefixA key is bk_{region}_{payload}{checksum}:
- bk_{region}_ — the prefix identifies the credential type and the region the key was created in. bk_us1_ keys are valid only against https://us1.platform.bird.com, bk_eu1_ keys only against https://eu1.platform.bird.com — the prefix is what official SDKs and the CLI use to pick the host. The fixed bk_ prefix is registered with GitHub secret scanning, so a Bird key leaked in a public repository is detected and reported.
- Payload — a long random string with 128+ bits of entropy.
- Checksum — the final 6 characters are a checksum of the rest of the key, letting a client reject a mistyped or truncated key locally before any request is made.
The full key is returned exactly once, in the response that creates it. Bird stores only an HMAC-SHA-256 hash — the plaintext cannot be retrieved again, and the dashboard shows only a short key_prefix (the first 12 characters). A lost key is revoked and replaced, never recovered.
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 — a bk_eu1_... key sent to us1.platform.bird.com, or vice versa. |
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 & 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 & regions — regional hosts and the region model
- Errors — the error envelope and catalog