Permissions

A token is a ceiling under its owner's authority, never a way over it.

The rule

Effective authority is the smaller of two things: what the person who minted the token may do, and what the token was scoped to.

Both are checked, separately, on every request. A token carrying workspace:admin that belongs to a member is refused by every route behind it, because the person is not an admin. A token carrying only tickets:read that belongs to an admin cannot write a ticket, because the token was not scoped to.

Scopes are stored as you asked for them and never narrowed when you mint. That matters in both directions: a token minted before a promotion starts working afterwards, and a token minted before a demotion stops. Freezing the authority you held on the afternoon you created it would get both of those backwards.

Item permissions still apply

Beneath roles, Shaire grants access to folders and lists on a ladder: read, comment, edit, full. A token inherits its owner’s position on that ladder exactly. Posting a comment needs comment on the subject; moving a ticket between two lists needs edit on both.

Nothing here is new machinery. A request from a token arrives carrying the same identity a browser request would have carried, and every existing rule runs unchanged.

Scopes do not narrow by resource. A token with tickets:write may write every ticket its owner may write, and there is no way to restrict one to a single list.

Two behaviours worth knowing before you debug one

The seat lock returns 402. A workspace over its plan’s seat count refuses almost everything for everybody except the owner, and a token is not an exemption. Four routes stay open so a locked-out script can read the plan and find out why it is failing, and each is marked in the reference.

Feature toggles hide screens without closing routes. A workspace with reports switched off still answers GET /api/reports/*. The toggle decides what the app shows, not what the API serves, so do not use one as an access control.

Finding out before you fail

GET /api/access/me answers what this caller may do in one request. A script that reads it at startup can say “this token cannot write to that list” instead of discovering it as a 403 halfway through a batch.