---
title: "Agent controls: scoped keys, spend limits, and safe retries"
description: "How Bird bounds what an AI agent can do: scoped API keys, idempotent sends, default-deny SMS destinations, daily spend limits per country, and a prepaid wallet."
canonical: "https://bird.com/docs/ai/agent-controls"
---

# 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](#choose-the-credential-the-agent-holds)             | The operations the agent can call         | `403`                                                  | The person who creates the key or approves the sign-in |
| [Idempotency key](#retry-a-send-without-sending-twice)           | Duplicate sends when a request is retried | The original response, replayed                        | The caller, on each request                            |
| [SMS destination allowlist](#allow-each-sms-destination-country) | The countries an SMS API send can go to   | `422 SMSDestinationNotEnabled`                         | A credential with `sms_management` write               |
| [SMS daily spend limit](#limit-daily-sms-spend-for-each-country) | SMS spend to one country in a day         | `422 SMSDestinationDailySpendExceeded`                 | A credential with `sms_management` write               |
| [Prepaid wallet](#bound-total-spend-with-the-prepaid-wallet)     | Pay-as-you-go spend                       | `402` for SMS. Some channels reject after they accept. | An organization owner or billing admin                 |

The destination allowlist and the daily spend limit on this page apply to SMS. [Verify](/docs/guides/verify/destinations) and [Voice](/docs/guides/voice/destinations) 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](/docs/ai/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**](https://bird.com/dashboard/profile/connected-apps). [API keys and OAuth tokens](/explained/platform/api-key-or-oauth-token-and-how-do-i-rotate-one) 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`:

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

[Authentication & API keys](/docs/guides/authentication) 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](/docs/guides/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](/docs/guides/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**](https://bird.com/dashboard/w/sms/destinations), with `bird sms destinations update`, or with the `sms_destinations_update` MCP tool:

```bash
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](/docs/guides/sms/sending-sms#before-you-send-enable-the-destination-country) 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:

```bash
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](/docs/guides/sms/sending-sms#before-you-send-enable-the-destination-country) 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** is refused at the API with `402`.
- **WhatsApp** is accepted, then rejected when Bird tries to charge it.
- **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](/docs/guides/billing-and-usage#the-wallet) 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](/docs/knowledge-base/billing/payment-methods-wallet) covers top-ups, automatic top-up, and low-balance alerts.

## Next steps

- [Self-serve signup](/docs/ai/self-serve-signup): create the account an agent works in, from a terminal.
- [Authentication & API keys](/docs/guides/authentication): scopes, expiry, rotation, and revocation.
- [Rate limits](/docs/guides/rate-limits): the request limits that apply across your organization's keys.
- [Give an agent its own phone number and inbox](/docs/ai/agent-number-and-inbox): the identities an agent sends and receives with.

## Related resources

- [Setting up your coding agent](/learn/basics/setting-up-your-coding-agent) (video)
- [What is an MCP server, and how does an agent use one to send messages?](/explained/platform/what-is-an-mcp-server-and-how-does-an-agent-send-messages) (answer)
- [Coding agents](/ai) (product)
- [Build with AI agents](/learn/paths/agents) (course)

[Get an implementation brief](/learn/workspace?topic=agents)
