Sign inGet Started

Agent controls: scoped keys, spend limits, and safe retries

An agent that sends through Bird holds a credential and spends your balance. Five controls bound what it can do. The first is the credential itself. The other four hold only while the agent's credential cannot change them, so start with the credential.

ControlWhat it boundsWhat the caller gets at the limitWho sets it
CredentialThe operations the agent can call403The person who creates the key or approves the sign-in
Idempotency keyDuplicate sends when a request is retriedThe original response, replayedThe caller, on each request
SMS destination allowlistThe countries an SMS API send can go to422 SMSDestinationNotEnabledA credential with sms_management write
SMS daily spend limitSMS spend to one country in a day422 SMSDestinationDailySpendExceededA credential with sms_management write
Prepaid walletPay-as-you-go spend402 for SMS and WhatsApp. Paid email is charged after it is sent.An organization owner or billing admin

The destination allowlist and the daily spend limit on this page apply to SMS. Verify and Voice each have their own destination settings, and they start differently. Email and WhatsApp have no destination allowlist and no daily spend limit, so the credential's scopes and the wallet are what bound an agent there.

Choose the credential the agent holds

An agent calls Bird with one of two kinds of credential. They differ in how far they reach.

  • An API key (bk_) carries the scopes you give it and belongs to one workspace. It cannot issue another key, and it cannot reach organization billing, members, or settings. Your code sends it as a bearer token. The CLI and the local MCP server (bird mcp) use the key in BIRD_API_KEY when one is set, in preference to a stored sign-in.
  • An OAuth token (bt_) is what the CLI and the MCP server hold after a person signs in. It carries the permissions that person approved, and never more than the person holds. Those can include api_keys write, sms_management write, and organization billing. An agent with such a token can issue keys, enable countries, and raise the limits on this page.

How much an OAuth token can do depends on how it was created:

  • bird auth login asks for read-only access. --scope asks for the set you name, and --yolo asks for every permission you are able to delegate. You approve the result in the browser.
  • A hosted MCP client can ask for every permission you are able to delegate. The consent screen lets you select which ones to grant. Clear the ones the agent does not need before you approve.
  • Self-serve signup has no consent screen. The credential it creates holds every permission the new organization's owner can delegate, organization billing included.

For an agent that runs unattended, create a scoped API key and give the agent that key. Keep the wider sign-in for the person who configures the workspace. You can revoke a tool's sign-in under Profile > Connected apps. API keys and OAuth tokens compares the two kinds of credential.

Scope each key to the products it needs

An API key carries a list of scopes, each a product area at read or write level. A key that sends SMS and does nothing else holds sms:write. A request outside the key's scopes returns 403, so a leaked or misused key reaches only what you granted it.

Three properties of a key hold whatever its scopes are:

  • A key cannot issue another key. Issuing and rotating keys needs api_keys:write, which is not available to API keys. A person approves it on a dashboard session or on a CLI or MCP sign-in.
  • A key stops at its workspace. It cannot reach billing, organization members, or organization settings.
  • A key can expire. Set expires_at when you create it, and the key returns 401 after that moment. Rotate or revoke a key at any time.

Create a key in the dashboard, or from a terminal. A CLI sign-in can put on a key only the scopes the sign-in holds itself, so this one asks for sms:write as well as api_keys:write:

Code example
bird auth login --scope api_keys:write --scope sms:write
bird api-keys create --name "Support agent" --scope sms:write

Authentication & API keys has the scope table and covers expiry, rotation, and revocation.

Retry a send without sending twice

An agent that loses a response cannot tell whether its request was accepted. Send an Idempotency-Key header with a unique value for each intended send, and repeat the same request with the same key when the outcome is unknown. Bird returns the original response and accepts the message once. A replayed response carries Idempotency-Replay: true.

The guarantee is one accepted operation per key within the retention window. It covers acceptance by the API. Delivery to the phone is reported separately, by the message status and its events.

The SDKs generate a key for each mutating call and reuse it for their automatic retries. On the CLI, pass --idempotency-key. Idempotency covers the key format, the retention window, and what happens when a key is reused with a different request.

Allow each SMS destination country

The SMS destination allowlist is default-deny. A send through the SMS API goes to a country enabled on the list, or it is rejected with 422 SMSDestinationNotEnabled before a sender is resolved, so no message is accepted. An agent pointed at an unexpected country is refused. This covers a send from your own code, from bird sms send, and from the sms_send MCP tool.

Verification codes do not use this list. Verify has its own list under Verify destinations, where every country starts enabled. A credential with verify write can therefore send a code by SMS to a country this allowlist blocks. If the agent holds verify, turn off the countries you do not serve on that page too.

Enable a country under SMS > Destinations, with bird sms destinations update, or with the sms_destinations_update MCP tool:

Code example
bird sms destinations update --destination NL=true

Changing the allowlist needs the sms_management scope at write level. A credential that holds sms alone can send to the enabled countries and cannot enable more. Give the sending agent sms, and keep sms_management for the credential that configures the workspace.

Sending SMS explains how the allowlist starts and how the home country is added.

Limit daily SMS spend for each country

Each destination country can carry a daily spend limit, in your wallet's currency. Once the day's spend to that country reaches the limit, new messages there are refused with 422 SMSDestinationDailySpendExceeded until midnight UTC. A limit of zero blocks the country.

Verification codes sent by SMS count toward the limit. When the limit is reached, Verify stops sending codes by SMS to that country and tries the next channel enabled for it. When no channel is left, the verification fails with 422 NoAvailableChannel.

Set a limit in the same three places as the allowlist. This command enables the Netherlands and limits it to 25 EUR a day, in a workspace whose wallet is in EUR:

Code example
bird sms destinations update --destination "NL=true;25EUR"

The limit is not exact. A change to a limit takes up to a minute to reach sending. Spend counts when a message is charged, so messages already accepted can take the day's total past the limit by what they cost. Plan the limit with that margin. bird sms destinations list shows each country's limit and the day's usage toward it.

Setting a limit needs the same sms_management write access as the allowlist, so a credential with sms alone cannot raise its own limit. Sending SMS has the full rules.

Bound total spend with the prepaid wallet

Pay-as-you-go sends draw on your organization's prepaid wallet. What happens when the balance cannot cover a send depends on the channel:

  • SMS and WhatsApp are refused at the API with 402. A message that was already accepted when its charge fails ends rejected and is not billed.
  • Email on a paid Email plan is charged shortly after it is sent, so the balance can briefly go below zero. Once the wallet has no balance or credit left, new email is refused with 402 until funds are added.
  • A delivery-time fee that the balance cannot cover is skipped, and the message still reaches its recipient.

An empty wallet stops further spend, but it does not cap spend to the exact balance. Fund it with a margin for sends that are charged after they are accepted. If automatic top-up is on, the wallet refills from a saved card when the balance falls below your threshold, so the balance alone no longer bounds what an agent can spend. Billing & usage is the source for these rules.

Billing operations need the organization's billing permission, org:billing. An API key cannot hold it, so no key can top up the wallet, change a plan, or read usage. An OAuth token can hold it when the person who approves the sign-in holds it and grants organization permissions, as an organization owner can. The credential from self-serve signup holds it from the start. Give an unattended agent a scoped key, and adding funds stays with the people who own the budget.

Payment methods and wallet covers top-ups, automatic top-up, and low-balance alerts.

Next steps