Should I use an API key or an OAuth token, and how do I rotate one?

A scheduled sender should keep working when the employee who configured it leaves. A tool acting for that employee needs access that follows their permissions instead.

Choose the credential around that ownership. Keep either credential out of browser code and logs because anyone holding it can attempt authenticated requests.

What does each credential let me do?

An API key acts for a workspace. An OAuth token lets an authorized tool act for a person.

Bird API keys begin with bk_. Their permissions belong to the workspace, so removing the creator does not invalidate them. Grant only the scopes the service needs to limit what an exposed key can do.

A key cannot perform organization-level operations, such as managing organization members or billing. Adding more workspace scopes does not remove that boundary.

When you sign in through the CLI or MCP server, you authorize a tool with a subset of your permissions. The tool receives a short-lived bt_ token. It manages token renewal, so do not copy that token into a service's secret manager.

Revoke an authorized tool through Profile > Connected apps. Use authentication to choose scopes and distinguish workspace keys from personal grants.

How do I rotate an API key?

Issue a replacement and deploy it before the old key's overlap ends.

You can rotate from the dashboard, with bird api-keys rotate, or through the api_keys_rotate MCP tool. CLI and MCP rotation require a personal grant with api_keys:write. An API key cannot hold that permission or rotate another key.

Rotation returns the replacement's token once. Store it immediately because later reads cannot recover it. The replacement retains the old name and IP restrictions. It also retains the permissions unless you supply new scopes.

Set grace_period to control the overlap. Its default is 24h, so complete deployment within that day. An earlier expiry on the old key still applies. Rotation never extends it.

Use grace_period: "0" when a leaked key should be revoked immediately. Cached validation can still accept it briefly, as described below.

1. Request rotation and save the returned token.
2. Deploy the replacement to each service before the overlap ends.
3. Confirm successful requests with the replacement through service logs.
4. Let the old key expire, or revoke it when the cutover is complete.

The rotation reference covers the command and its options.

What can go wrong during rotation?

A lost response can leave you with an issued replacement whose token you never saved.

Use the same Idempotency-Key when retrying the rotation request so Bird can replay its response. A key can rotate only once. Without the same idempotency key, repeating the rotation returns 409. Rotate the replacement for a later planned change.

A revoked key cannot be rotated. Create a new key if the original is already revoked.

The replacement has no expiry, even when the original did. You cannot add an expiry afterward. Create a new key with expires_at when it must stop working at a known time.

For a deployment with an uncertain duration, create a second key and manage the overlap yourself. Deploy it before revoking the original. A rotation's grace period cannot be extended after the request.

How quickly does revocation take effect?

A revoked key can remain accepted for up to five seconds while cached validation expires.

Treat an exposed key as usable throughout that window. Revocation is permanent, so a revoked key cannot be reactivated. Bird keeps its record for audit.

Use key_prefix or fingerprint to identify a key in support conversations. Never include the full credential, because those identifiers are sufficient to distinguish it without granting access.

Which credential should I choose?

Choose according to who owns the workload and which permissions it needs.

1. API key: a service that should keep working independently of its creator.
2. OAuth grant: a CLI or agent acting within a person's permissions.
3. Rotation: a replacement key you can deploy during a known overlap.
4. New key with expiry: a credential that must stop working at a specific time.