Tokens & Abilities
Scoped, expiring API tokens — what each ability unlocks, how personal and team tokens differ, and how rotation works.
Creating a token
Personal tokens are created under Settings → API tokens, where you choose the type: API (the default ability set) or Local runner (the runner ability only). Team tokens are created under the team's settings (admins and owners only) and are API tokens. A token is shown once, at creation — store it securely. 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. Tokens created in the UI get the full default set:
| Ability | Unlocks |
|---|---|
agent:run | Running sessions (POST /api/v1/chat). |
sessions:read | Listing and reading sessions. |
inspect | Discovery, tool listing, and manual tool calls. |
targets:read / targets:write | Reading and managing saved targets. |
collections:read / collections:write | Reading and managing collections, triggering runs. |
reports:read | Collection-run reports and PDFs. |
One ability is deliberately excluded from the default grant: runner, which lets a process claim and execute Local-runtime jobs. A runner token carries runner and nothing else — so a leaked runner token can't read your sessions or trigger runs, and a leaked default token can't claim jobs.
Personal vs team
A personal token acts as you, in your personal workspace. A team token is scoped to its team — and the role matrix applies through it: writes (targets, collections, triggering runs) require the token's team role to be admin or owner; members run sessions and read everything. The two lists never mix: personal tokens don't appear in team settings or vice versa.
Expiry, revocation, rotation
- Expiry — tokens expire 180 days after creation. Create a new one and swap it in before the old one lapses; there is no renewal in place.
- Revocation — deleting a token takes effect on the next request. The list shows each token's last use, 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. Session runs (POST /api/v1/chat) are limited by your plan's usage tier, and manual tool calls at 60 per minute. Limits apply per user, not per token — minting more tokens doesn't raise them.