These are two different credentials for two different kinds of caller, and the distinction is not about security level. It is about whether a person is present.
What is the difference between a key and a token?
An API key authenticates a service. It starts bk_, followed by a region segment that routes your request, then a payload and a six-character checksum, so a mistyped or truncated key is rejected before it is looked up. A key belongs to a workspace rather than to the person who created it, which is why keys survive an employee leaving.
It is also why a key can never reach an organization-level operation, and that limit is worth taking literally. It is not a convention about what keys are for: authorization refuses any operation whose required scope begins org: when the caller is a key, so no set of grants gets one past it. Billing, SSO, organization members, IP pools and audit are all on the far side of that line.
An OAuth token authenticates a person, through a tool acting for them. When you sign in to the Bird CLI or the MCP server you log in through the browser, choose a workspace, and grant a subset of your own permissions. The tool receives a short-lived bt_ token that can never exceed what you hold, and you can revoke each tool's access individually from your profile.
So the choice is usually made for you. A server workload gets a key. A command line or an agent that a person authorised gets a token, and the tool manages it, which is why you should not copy a bt_ token or put one in a secret manager.
That boundary has a consequence people meet the hard way: an organization-level task cannot be automated with a key at all. The CLI can do some of them, and that is not an inconsistency, it is the same rule seen from the other side. The CLI is carrying a person's token, which can hold org: scopes, where a key cannot.
One property of keys shapes everything below: the full key is returned once, in the response that creates it, and is never retrievable again. Afterwards you see only the first 15 characters as key_prefix and a stable 12-character fingerprint, which is what you quote in a support conversation instead of the key itself.
How do I rotate a key?
From the key's own row in the dashboard, or with bird api-keys rotate, and the mechanism does the thing people otherwise build by hand.
Rotating issues a new key carrying the same name and IP restrictions, and the same permissions unless you choose a new set. The new token is shown once, like any newly created key.
The part that matters operationally is what happens to the old one: it keeps working for a grace period, 24 hours by default. That overlap is the whole point, because it means you can rotate first and deploy second rather than racing. Set the grace period to zero when you want the old key dead immediately, which is what you want if the reason you are rotating is that it leaked.
Two constraints matter if you script it. A key can be rotated once: a second rotation of the same key is refused, and you rotate the replacement instead. And the replacement carries no expiry even when the key it replaces had one, with no later call able to add one, so re-create rather than rotate when the expiry is the point.
A key that has already been revoked cannot be rotated.
Can an integration rotate a key on its own?
Not with its own key, and the reason is deliberate rather than a gap in the surface.
Rotation is scriptable, but only as a person. It runs on three surfaces: the dashboard, bird api-keys rotate on the CLI, and the api_keys_rotate MCP tool, alongside create. It is deliberately absent from the SDKs, because all three of the others run on a delegated grant or a session, while an SDK runs on a key, and the permission that mints a key sits outside the ceiling any bk_ key can hold. A key cannot mint another key, itself included. Listing, reading, updating, revoking and every IP-restriction operation stay in the dashboard.
So a person with a grant can rotate from a shell or an agent loop. An unattended service holding only its own key cannot, and builds the overlap instead:
- Create a new key with the same scopes.
- Deploy it to your services.
- Watch the old key's
last_used_onuntil traffic has moved. - Revoke the old key.
The cost of doing it this way is not effort, it is the audit trail. A rotation records the link between the old key and its replacement, so the history reads as one credential's lifecycle. A manual overlap looks like an unrelated create and revoke to anyone reading the log later.
How fast does revoking a key take effect?
Fast, but not instantly.
Revocation is permanent. A revoked key cannot be reactivated, and its record is kept for audit rather than deleted.
Key validation runs through a short-lived cache, and a revoke does not clear it, so a revoked key can still be accepted for up to five seconds afterwards. At real throughput that is a lot of requests, so treat a leaked credential as live until the window has passed rather than assuming the revoke landed the moment you clicked it.
What should I never do with either?
Three things, each of which follows from something above.
Do not plan to read a key back. It is returned once. If you lose it, you revoke it and create a new one, so store it when you create it or use rotation to issue a fresh one.
Do not store a bt_ token. Those belong to the tool that obtained them and are refreshed for you; treating one as a long-lived credential defeats both the expiry and the per-tool revocation.
Do not use a personal token for a server workload. It is scoped to a person's permissions, so it changes when their role changes and dies when they leave. That is exactly the failure a workspace-bound key exists to avoid.
Authentication has the full key anatomy, the scope and level model, and the OAuth flow.