Authentication

Every Bird API request authenticates with a Bearer token.

Bearer token header

curl https://api.bird.com/v1/emails \
  -H "Authorization: Bearer bird_live_xxxxxxxx"

The same header works on every endpoint — emails, SMS, voice, WhatsApp, verifications, flows, TTS, templates, and every configuration resource.

Test keys vs live keys

bird_test_* — sends only to the sanctioned test recipients (delivered@bird.dev, +15005550006, +15005550010, +15005550009). Free. Full feature parity with live.
bird_live_* — production traffic. Billed by usage. Unlocked when you add a payment method and verify a sender.

User-Agent requirement

All API requests must include a User-Agent header. Requests without this header are rejected with 403. Our SDKs set it automatically; if you're calling the API directly, identify your app.

curl https://api.bird.com/v1/emails \
  -H "Authorization: Bearer bird_live_xxxxxxxx" \
  -H "User-Agent: acme-checkout/1.4.0" \
  -H "Content-Type: application/json" \
  -d '{ "to": "delivered@bird.dev", "from": "Bird Test <onboarding@bird.dev>", "subject": "Hi", "text": "Hello." }'

The default limit is 100 requests per second per team. Higher limits are available on Scale and above. When you hit the limit the API returns 429 rate_limited with a Retry-After header — see /docs/errors.

Scopes

Keys are scoped at creation. Use the narrowest scope that covers the work.

Scope	Grants
`emails:send`	`POST /v1/emails`
`sms:send`	`POST /v1/sms`
`voice:create`	`POST /v1/voice/calls`
`whatsapp:send`	`POST /v1/whatsapp/messages`
`flows:run`	`POST /v1/flows/{flow}/runs`
`verifications:*`	`POST /v1/verifications`, `/check`, `/retry`
`*:read`	`GET` on every resource the key can otherwise act on
`webhooks:manage`	Subscribe, list, and delete webhook endpoints
`templates:manage`	Create, update, and delete templates across channels

Rotating keys

Keys rotate without downtime. The dashboard issues a new key, keeps the old one valid for a 24-hour overlap window, and surfaces the cutover so you can update your environment before revoking the previous key.

MCP keys

MCP clients (Claude, Cursor, Cline) use scoped keys that can read everything and send only to the sanctioned test recipients. See /docs/mcp for the install flow.