Tokens and abilities
API tokens are scoped and expire. This page covers what each ability unlocks, how personal and team tokens differ, and how to rotate them.
Creating a token
Personal tokens are created under Settings › API keys (also in the account menu as API keys). Enter a name, such as ci-nightly, and click Create token. If your account has access to the local runtime, a type menu beside the name also offers Local runner (the runner ability only); otherwise every token is an API token.
Team tokens are created in the team's Team settings, under Team tokens (admins and owners only). While a team is your current workspace, Settings › API keys links to them with Open team tokens.
A token is shown once, when you create it. Copy it and store it somewhere safe. Send it as Authorization: Bearer <token>.
Abilities
Every token carries a set of abilities, and every API route requires one, with a single exception: GET /api/v1/models needs a valid token but no ability. API tokens get the full default set. The ability names are part of the API and keep their original wording:
| Ability | Unlocks |
|---|---|
agent:run | Starting runs (POST /api/v1/chat). |
sessions:read | Listing and reading runs. |
inspect | Discovery, tool listing and calling tools by hand. |
targets:read / targets:write | Reading and managing saved targets. |
collections:read / collections:write | Reading and managing collections, and starting their runs. |
reports:read | Collection-run reports and PDFs. |
One ability is left out of the default set on purpose: runner, which lets a process claim and answer jobs for the local runner. A runner token carries runner and nothing else. A leaked runner token can't read or start runs, and a leaked API token can't claim jobs.
Personal and team tokens
A personal token acts as you, in your own workspace. A team token is scoped to its team, and the role table applies through it: writes (targets, collections, starting collection runs) need the token's team role to be admin or owner; members can start runs and read everything. The two lists never mix: personal tokens don't appear in Team settings, and team tokens don't appear in Settings › API keys.
Expiry, revoking and rotation
- Expiry — tokens expire 180 days after they are created. There is no renewal: create a new one and swap it in before the old one lapses.
- Revoking — Revoke takes effect on the next request. Each list shows a token's Last used date, so stale ones are easy to spot.
- Rotation — create the replacement first, deploy it, then revoke the old token. The overlap costs nothing.
Rate limits
The API allows 120 requests per minute overall. Runs (POST /api/v1/chat) are limited by your plan, and calling tools by hand by 60 per minute. Limits apply per user, not per token, so creating more tokens doesn't raise them.
Something wrong on this page?