Authentication & API keys

How requests authenticate

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

await bird.email.send({
  from: "hello@yourdomain.com",
  to: ["delivered@messagebird.dev"],
  subject: "Hi",
  text: "Hello.",
});

import os

from bird import Bird

client = Bird(api_key=os.environ["BIRD_API_KEY"])

client.email.send(
    from_="hello@yourdomain.com",
    to=["delivered@messagebird.dev"],
    subject="Hi",
    text="Hello.",
)

client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
	log.Fatal(err)
}

_, err = client.Email.Send(context.Background(), bird.EmailSendParams{
	From:    "hello@yourdomain.com",
	To:      []string{"delivered@messagebird.dev"},
	Subject: "Hi",
	Text:    "Hello.",
})

use MessageBird\Bird;

$bird = new Bird(getenv('BIRD_API_KEY') ?: '');

$bird->email->send(
    from: 'hello@yourdomain.com',
    to: ['delivered@messagebird.dev'],
    subject: 'Hi',
    text: 'Hello.',
);

export BIRD_API_KEY="bk_us1_..."

bird email send \
  --from hello@yourdomain.com \
  --to delivered@messagebird.dev \
  --subject Hi \
  --text Hello.

curl -X POST https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from": "hello@yourdomain.com", "to": ["delivered@messagebird.dev"], "subject": "Hi", "text": "Hello." }'

Anatomy of a key

bk_us1_Ab3xKq9mP2wR5tY8uI1oL4nJ2kQ9m
└┬┘└┬┘ └──────────┬──────────┘└─┬──┘
 │  │          payload      checksum
 │  └ region (routes the request)
 └ Bird key prefix

• Prefix: bk_{region}_ names the credential type and its region. The fixed, distinctive prefix is what lets secret scanners recognize a Bird key in code, and the region segment routes your request to the right host.
• Payload: 23 random characters carrying 136 bits of entropy.
• Checksum: the last 6 characters are a checksum of the rest of the key, so an SDK or the API can reject a mistyped or truncated key immediately, before it is ever looked up.

Creating a key

• The scope set is immutable. Scopes cannot be added or removed on an existing key. To change what a key can do, create a new key with the right scopes and revoke the old one; every key's permissions stay exactly what they were when it was issued and audited.
• Expiry is immutable too. Set expires_at when a key should stop working at a known time (a contractor's engagement, a migration window). Past that moment the key returns 401; a key without an expiry lives until revoked.
• Key management stays with people. Creating and revoking keys requires the api_keys:write permission, held by the workspace admin and developer roles (see Users, teams & roles) and never grantable to an API key itself. A leaked key cannot mint more keys.

Scopes & levels

Revoking a key

1. Create a new key with the same scopes.
2. Deploy the new key to your services.
3. Watch the old key's last_used_on until traffic has moved.
4. Revoke the old key.

Keys belong to the workspace

• Keys survive departures. When an employee leaves and their user account is removed, the keys they created keep working. You never have a production outage because the person who clicked "create" left the company. (Their departure is still a good prompt to rotate keys they had access to.)
• The key's reach stops at the workspace. It can never perform organization-level operations: billing, org members, org settings.

The delegated path: OAuth tokens for the CLI and MCP server

Next steps

• Authentication reference: request header semantics and error responses
• Regions: regional hosts and routing
• Users, teams & roles: who can manage keys
• Workspaces: the workspace a key binds to