Getting started
Scopes
Every scope a Backlog API token can carry, and what it opens.
A scope narrows what a token may be used for. It never widens what its owner may do: every request runs the same
policies the web app does, and both have to agree. Pick as few scopes as the job needs; a read-only token is the right
answer for a dashboard, a report or a status page. A token made without choosing gets only issues:read.
| Scope | What it opens |
|---|---|
issues:read |
Issues, comments, relations, and the issues you starred |
issues:write |
Create, update, archive and delete issues; comments and relations |
projects:read |
Projects, milestones and project updates |
projects:write |
Create and change those |
cycles:read |
Cycles and their progress |
cycles:write |
Change cycles and what sits in them |
customers:read |
Customers and what they asked for |
customers:write |
Create and change customers and their requests |
initiatives:read |
Initiatives and the projects under them |
initiatives:write |
Create and change initiatives |
activity:read |
The workspace activity timeline |
activity:write |
Write notes onto the timeline |
workspace:read |
Teams, members, labels, workflow states, saved views |
workspace:write |
Create labels and change team procedures |
inbox:read |
Your notifications |
inbox:write |
Mark notifications read, snoozed or archived; register a mobile device |
documents:read |
Knowledge base articles |
documents:write |
Write, publish, verify, link and delete articles (MCP only) |
decisions:read |
The decision log (MCP only) |
decisions:write |
Record and settle decisions (MCP only) |
triage:write |
Accept, decline and merge reports waiting in triage (MCP only) |
notify:read |
Notify: contacts, segments, mailings and their results |
notify:write |
Notify: write mailing drafts and send test mails |
notify:send |
Notify: send and schedule mailings to customers (REST API only) |
incidents:read |
Incidents, timelines and updates |
incidents:write |
Declare incidents, post updates, change status, severity and roles |
assets:read |
Assets, their types, fields, history and relations |
assets:write |
Create and change assets; issue, return and renew them; administrators also types and fields |
favorites:write |
Star and unstar issues, projects and teams for yourself |
Scopes are families on purpose
inbox:* and activity:* are separate from issues:read. An inbox is a record of what was addressed to one person,
and the timeline merges comments, project history and notes into a readable account of who did what all week.
Somebody handing a script issues:read has not agreed to either, and should not find out they did.
notify:send is the one scope that cannot be taken back: a mailing reaches customers. It is never part of another
scope, and the endpoints that use it are throttled hard and ask for the same confirmation as the screen.
Which endpoint needs which scope
Each endpoint on the reference pages shows its scope in the bar under the heading. A missing scope answers 403.
Two endpoints need more than one: GET /api/v1/saved-views/{view}/issues needs
workspace:read and issues:read.
The Docs and Chat APIs
They have their own permission models: capabilities on an integration for Docs, and a
contracts scope for the contract endpoints in Chat.