Documentation
Sign inGet started
Get started
Guias
API Reference
SDKs
CLI
Base de conhecimento
Changelog

API key management

An API key is an application credential. It belongs to one workspace, and an application holding it can call the Bird API within its assigned scopes. You can manage keys in the dashboard or through the API. For the full technical contract, see Authentication & API keys.

Where keys live

Open API keys, pinned near the bottom of the sidebar alongside Webhooks and Logs. The page lists each key's name, masked prefix, scopes, status, expiration, and last-used date.
The API Keys page in the Bird dashboard, listing keys with their masked prefix, scopes, and last-used time
Creating and revoking keys requires the right workspace role: Admins and Developers have it. See Users, teams & roles.

Creating a key

  1. On the API keys page, choose to create a new key.
  2. Name it for its job, such as "Billing service production," rather than for a person.
  3. Pick scopes. Each scope has a read or write level. Grant only the scopes and levels the application needs.
  4. Create the key and copy the secret immediately.

The secret is shown once

The full key appears once, when you create or rotate the key. Bird cannot show the secret again. Copy it directly to a secret manager or deployment configuration. If you lose it, rotate or replace the key.
A key's scopes cannot be edited. To change them, create a replacement key, update the application, and revoke the old key.

Revoking a key

Revoke a key when it is no longer needed or you suspect it leaked. Revocation is permanent. Key validation uses a short-lived cache, so a revoked key may keep working for up to five seconds before requests fail authentication.
If you suspect a key has leaked, revoke it and deploy a replacement. Requests fail until the application uses an active key.
To rotate without downtime, use the rotation action and keep its default 24-hour grace period. Deploy the replacement before the grace period ends. Set a shorter grace period only when you can update callers sooner.

Everything is recorded

Key creation, rotation, and revocation appear in your organization's audit log. Include revoked keys in the key list to review their metadata.

Good habits

  • Use one key per application and environment. Separate staging and production keys so you can revoke one without affecting the other.
  • Watch the last-used column. Revoke inactive keys that are no longer needed.
  • Never put keys in client-side code or public repositories. Keys belong in server-side configuration and secret managers only.

Next steps