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.
| Control | What it bounds | What the caller gets at the limit | Who sets it |
|---|---|---|---|
| Credential | The operations the agent can call | 403 | The person who creates the key or approves the sign-in |
| Idempotency key | Duplicate sends when a request is retried | The original response, replayed | The caller, on each request |
| SMS destination allowlist | The countries an SMS API send can go to | 422 SMSDestinationNotEnabled | A credential with sms_management write |
| SMS daily spend limit | SMS spend to one country in a day | 422 SMSDestinationDailySpendExceeded | A credential with sms_management write |
| Prepaid wallet | Pay-as-you-go spend | 402 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 inBIRD_API_KEYwhen 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 includeapi_keyswrite,sms_managementwrite, 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 loginasks for read-only access.--scopeasks for the set you name, and--yoloasks 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_atwhen you create it, and the key returns401after 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:
bird auth login --scope api_keys:write --scope sms:write
bird api-keys create --name "Support agent" --scope sms:writeAuthentication & 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:
bird sms destinations update --destination NL=trueChanging 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:
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 endsrejectedand 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
402until 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
- Self-serve signup: create the account an agent works in, from a terminal.
- Authentication & API keys: scopes, expiry, rotation, and revocation.
- Rate limits: the request limits that apply across your organization's keys.
- Give an agent its own phone number and inbox: the identities an agent sends and receives with.
Related resources
Continue with the documentation, guides and examples for this topic.