API keys
Minting keys, agent profiles, expiry, and monitoring key usage.
API keys authenticate programmatic access - scripts, integrations, CLI
sessions and AI agents. A key is shown once at creation; orboto stores
only a hash. Keys have the form orb_... and are sent as
Authorization: Bearer <key>.
Minting a key
- For yourself - from your Profile → API keys section. The key acts with your own permissions.
- For a bot - administrators mint keys on a bot account's behalf from Admin → Users → the bot's row → API keys tab. The key acts with the bot's project memberships and roles, not the admin's.
Every key gets a name (so you can tell integrations apart) and an optional expiry date. Admin-minted keys default their agent flag to the account type - a bot's key is an agent key unless you say otherwise; self-service keys default to off and you opt in explicitly.
Agent profiles
When a key is marked as an agent key, an admin minting it on a bot's behalf can also set:
- Agent kind - a free-text label such as
coding,orchestrator,reviewer,runnerorchat. - Model tier -
frontier,standardorsmall.
Workspace rules for agents can target these attributes, so a lightweight worker gets a different instruction set than an orchestrator - without the agent declaring anything per call. Marking a key as an agent key also makes work-routing policies apply to it: human-reserved tickets are withheld from autonomous pulls, and the workspace's autonomy-pause switches take effect. The agent kind and model tier fields are only available on admin-minted bot keys, not on self-service keys from your own profile.
Rotating and revoking
- Rotate issues a fresh secret for the same key row (same name, same agent profile) and immediately invalidates the old secret - use this instead of creating a new key when you just need a fresh credential.
- Delete removes a key outright; access is cut instantly.
- Deactivating the owning user or bot invalidates all of their keys.
One key per integration or agent lane - never share a key across systems, so a compromised or misbehaving integration can be revoked without affecting the others.
Monitoring usage
Admin → API keys is a workspace-wide, live-updating dashboard of every key's request volume - not where you create keys. It shows, per key: the owner, total requests, a share-of-traffic bar, last-used time and expiry, searchable and sortable. Keys are flagged automatically:
| Flag | Meaning |
|---|---|
| Dominant | This key accounts for ≥20% of all requests (and >100 requests) - worth checking it's not a runaway loop. |
| Stale | No requests in the last 90 days - a candidate for cleanup. |
| Expired | Past its expiry date. Still shown for visibility even though it no longer authenticates. |
| Suspended | The owning user or bot is deactivated - the key 401s regardless of its own state. |
Troubleshooting
A key stopped working with no visible change to the key itself. Check Admin → API keys for a Suspended or Expired flag - the owning account may have been deactivated, or the expiry date passed.
One key is responsible for most of the traffic. The Dominant flag surfaces this automatically; check whether that's an expected orchestrator key or a misbehaving loop retrying without backoff.
An agent isn't getting the instruction set you expected. Confirm the key's agent kind and model tier match what your workspace rules target - these are set on admin-minted bot keys only, under the user's API keys tab.