HOW-TO

Choose the right scopes

Least privilege, and the three scopes that are wider than they look.

Scopes come in read / write pairs per domain: products, tasks, decisions, documents, activity, assets, instructions, and so on. The full list, with the tools each one unlocks, is in the scope reference.

Start from what the agent is for

The agent...	Give it
Reads and summarises	`products:read`, `tasks:read`, `decisions:read`, `documents:read`
Works the board	the above plus `tasks:write`
Advises on decisions	the above plus `decisions:write` (it still cannot resolve one)
Writes documentation	the above plus `documents:write`

Adding a scope later means minting a new token. That is mildly annoying and much better than the alternative.

Three that are wider than they look

infra:read enumerates every server the organization runs, across all workspaces. It is deliberately not implied by any product-level read, and it is the one scope worth a second thought before granting.
credentials:reveal returns stored secrets in plaintext. Everything else in the product goes out of its way never to do this.
workspace:export produces a bundle of the entire workspace in one call. Every other read is narrow; this one is not.

What no scope grants

Some acts are refused to agents whatever their token says: creating workspaces or organizations, inviting or revoking members, registering agents, resolving decisions, and every hard delete. You cannot grant these by widening a token, which is the point - the ones that matter are exactly the ones somebody might grant by accident.

Two names for one thing

products:* and projects:* are equivalent, and holding either satisfies the other. The projects spelling is the older name kept working; write new tokens with products.