Scopes

Every API token carries an explicit scope set. Human logins (session cookies) hold every scope implicitly, subject to their board role; tokens are limited to the scopes they were minted with. The source of truth is packages/shared/src/scopes.ts.

Scope vocabulary

Scope	Grants
boards:read	read boards, lists, members, activity, labels, fields (implies cards:read)
boards:write	create/rename/archive boards & lists; manage labels + field definitions. Implies boards:read, cards:write, cards:read, comments:write
cards:read	read cards, assignees, card labels, field values, attachments, card activity
cards:write	create/edit/move/archive cards, plus assignees, labels, field values, attachments (implies cards:read)
comments:write	add/edit/delete comments (implies nothing else — a comment bot can't read or edit cards)
members:write	add/remove board members & change roles (reads ride on boards:read)
webhooks:write	manage webhook subscriptions
integrations:write	install/manage integrations; emit integration (vcs.*) events
automations:write	create/update/delete board automation rules
tokens:write	mint/list/revoke tokens (see delegation rule below)
notifications:read	read your own notification inbox
notifications:write	triage (mark read) your inbox (implies notifications:read)
sessions:read	read agent sessions and their event trails
sessions:write	drive/answer agent sessions (implies sessions:read)
board:<id>	board leash — confines every other scope to that one board
presence:hidden	the principal participates and receives events but is not listed in board presence (a marker, not a permission gate)

Implication table

Holding a key scope also satisfies the implied scopes. The rule: broad implies narrow, so existing broad tokens keep working; narrow tokens are truly least-privilege.

Holding…	…also satisfies
boards:write	boards:read, cards:write, cards:read, comments:write
boards:read	cards:read
cards:write	cards:read
notifications:write	notifications:read
sessions:write	sessions:read

Never implied by anything — these must be granted explicitly, and the domain double-gates them on top of the board-role check:

members:write · webhooks:write · integrations:write · automations:write · tokens:write

comments:write implies nothing. The session scopes (sessions:*) are admin-independent and never implied by the broad content scopes — driving or answering a session is a distinct authority.

The board leash (board:<id>)

Add a board:<id> scope to confine a token to a single board. A leashed token:

• has every other scope restricted to that board;
• cannot create boards (there is no board context, so a board-scoped check fails closed);
• sees only the leashed board(s) from GET /api/boards and board_read.list;
• has its notification inbox filtered to the leashed board(s).

Actor-level scopes (tokens:write, notifications:read, notifications:write) act on the actor, not a board resource, so a leash does not gate them out (though the inbox is still filtered to the leashed board).

Token delegation

A tokens:write token can mint only a strictly weaker token:

• a scope subset of its own;
• a same-or-narrower board leash;
• an expiry no later than its own;
• and it cannot re-delegate tokens:write.

Human mints are the root of every delegation chain. Over OAuth, tokens:write can never be granted.