Scopes, roles and plans

The five scopes

Scope	Opens	On the token form
`read`	Search, the documents and their facts, people & things, the Checkup, bundles, imports	Every token has it
`write`	Change things: mark handled, correct, file as, link, move, share; put documents in	Change things
`files`	The original file and the pages of a document as pictures	Download files
`identifiers`	Account, policy and license numbers in what comes back	See account and policy numbers
`ask`	Thaw’s answer to a question, and the email drafts	Ask

Every endpoint in the reference carries a chip naming the scope it needs. Without it the answer is 403 with scope naming the one to ask for and a WWW-Authenticate header saying insufficient_scope.

Without identifiers, account, policy and license numbers are left out of every answer rather than masked: a fact whose role is an identifier does not appear, and a search that matched on one says so in matched_on without repeating the number.

The role

A token can never do more than the person it belongs to. The role in a family or business decides what the form offers and what a call may do:

Role	Reads	Changes	Adds documents	Files	Identifiers
Owner, member	yes	yes	yes	yes	yes
Viewer	yes	no	no	yes	no
Guest, view	what the grant allows	no	no	yes	no
Guest, edit	what the grant allows	no	in the app	yes	no
Guest, upload only	nothing	no	in the app	no	no

Only an owner or a member can tick “Change things” on a personal token, so only they change anything through one. A guest holds a grant rather than a membership - a professional let in for a while, or someone let in on one bundle - and the API walls them the same way the page does: a bundle guest sees that bundle, the Library narrowed to it, and Ask over it, and nothing else. GET /account says the role, and its can.change says whether a change would go through here once the role, the plan and the token have all had their say.

The plan

The API comes with the paid plans (Personal, Family, Business). A personal token on a Free family is refused at the door with the sentence that says which plan it comes with. One thing is different: an assistant connection reads on every plan, because every plan may look things up from an assistant; changing things comes with the paid plans.

Adding a document is not changing one. The routes that take a document in (POST /documents, the note, the uploads) ask for the role and the write scope and never the plan, so a Free family’s shortcut can put paper in.

Which wall said no

A refusal names its wall in detail, in order: the role first (“Your role here is read-only, so a token of yours can read but not change anything”), then the plan (“A token can look things up on the Free plan. Changing things comes with Personal: …”), then the scope, which is the only one a caller can step up to, and so the only one that names a scope. Errors has the shapes.