Scopes
Twelve values: four nouns crossed with read and write, plus search, reports and two for the workspace.
You tick these when you mint a token. Every endpoint in the reference names the one it needs.
Read and write are separate everywhere. A token carryingtickets:write cannot read tickets unless it also carries tickets:read. That is more boxes to tick and it means a credential you gave to a filing script cannot be used to export your workspace.
Ticking a scope grants nothing on its own. Authority is the smaller of what you may do and what the token carries, so workspace:admin on a member's token is refused by every route behind it. See Permissions.
The twelve
tickets:read
Read tickets, lists, folders, custom field definitions, templates, recurrences, milestones and cycles.
Most of the API sits behind this one. A token that reads nothing else usually still wants it, because a ticket's status and assignee are ids that have to be resolved against the workspace.
tickets:write
Create and change tickets, move them between lists, reorder them, and manage lists, folders, templates and recurrences.
Soft deletes are here too. A ticket deleted with this scope goes to the trash and can be restored; the routes that delete permanently are not on this API at all.
pages:read
Read pages, their version history and page templates.
pages:write
Create, update, move and soft-delete pages, and restore an earlier version.
comments:write
Post and edit comments, react, resolve threads, follow items, and mark notifications read.
It also carries the personal-state writes — watching, favouriting, notification triage and the digest schedule. Those could each have been argued into a read scope one at a time, which is how a read-only credential ends up writing.
time:read
Read time entries and whichever timer is currently running.
time:write
Start and stop timers, log entries by hand, and amend them.
search:read
Search across tickets, pages and milestones in one request.
Results are already filtered to what the caller may see, so a guest's search returns a guest's workspace.
reports:read
Read the six reports: workload, burndown, cycle time, time, throughput and velocity.
workspace:read
Read the workspace vocabulary a client needs to render anything: statuses, status groups, tags, members, teams, and the current plan.
Statuses are per workspace, so nothing may hard-code "Done". Reading them is how a client learns what the workspace calls its columns.
workspace:admin
Change the workspace itself: statuses and their transitions, tags, teams, access grants, git repositories, and read the audit log.
One scope rather than eight, because everything behind it already asks for an admin. Ticking it does not make the token's owner an admin — if they are not one, every route behind it still refuses.
Why not one scope per endpoint
A scope per route produces a matrix nobody maintains and a consent screen nobody reads. Four nouns and two verbs is a sentence you can check before pasting a token into a CI job: this may read my tickets and write comments, and nothing else.
workspace:admin is one scope rather than eight for the same reason. Everything behind it already requires an admin, and a token that may edit the status vocabulary but not the tag vocabulary is a distinction with no user behind it.
How far a scope reaches
A scope covers a noun across the whole workspace: tickets:write reaches every ticket its owner may write. To confine an integration to part of a workspace, confine the person who mints the token. Item permissions are per folder and per list, and a token inherits them exactly. See Permissions.
comments:read8 endpoints
Read comment threads, reactions, the activity feed, watchers, favourites and the notification inbox.