Scopes
The full scope vocabulary, what each one unlocks, and why some capabilities have no scope at all.
Scopes are resource:action — coarse enough that the admin granting them can
read the list and understand what they are agreeing to, fine enough that a
"sync tasks nightly" integration does not also get the ability to delete a
project.
A scope name is a permanent promise. Renaming one would break every token carrying it; repurposing one would silently widen what existing tokens can do. Scopes are added, never renamed and never reused.
The vocabulary
| Scope | Grants |
|---|---|
tasks:read | Read tasks, subtasks, links, followers and activity history |
tasks:write | Create, update, assign, link and transition tasks |
projects:read | Read projects, labels, milestones, sprints and project members |
projects:write | Create and update projects, labels, milestones and sprints |
comments:read | Read comments |
comments:write | Post, edit, delete and react to comments |
attachments:read | List and download attachments |
attachments:write | Upload, rename and delete attachments |
workflows:read | Read statuses, transitions and workflow definitions |
workflows:write | Create and modify statuses, transitions and workflows |
customfields:read | Read custom field definitions and values |
customfields:write | Create, reorder and modify custom fields |
members:read | Read the workspace member roster |
reports:read | Read every report — throughput, cycle time, burndown, velocity, aging, workload |
standups:read | Read standup entries, blockers, history and worklists |
standups:write | Post, redraft and skip standup entries |
webhooks:read | Read endpoints, the event catalog and delivery history |
webhooks:write | Create, modify, test and replay webhook endpoints |
What has no scope, and why
There is no admin:* scope, and there never was one to remove. Everything a
*:write scope cannot reach is simply not published to tokens at all:
- Organization settings, SSO configuration and billing
- Seat and membership management
- Inbound-email routing
- API tokens themselves
That last one is the load-bearing exclusion. A token that could mint another token with broader scopes defeats the entire model, so token management is not merely scope-gated — it is absent from the published surface. No combination of scopes reaches it.
There is also no members:write. Adding people and changing their roles is
exactly how an automation would escalate its own reach, so it stays a human
action.
Read does not imply write
tasks:write does not include tasks:read. If your integration creates a task
and then reads it back, grant both. They are separate on purpose: a
fire-and-forget intake webhook genuinely does not need read access to the
backlog, and giving it some because the API assumed so would be a widening
nobody asked for.
Choosing scopes
Grant the smallest set that makes the integration work, and prefer a project-restricted token when the integration only touches one project. Two narrow tokens are better than one broad one — they fail separately, they can be revoked separately, and the audit trail tells you which system did what.
The machine-readable catalog, including the human-readable label shown to the admin who approves the grant, is available at:
GET /api/v1/api-tokens/scopes/