Concepts

Roles and scopes

Scopes narrow a role. They never widen it.

On this page

A credential acts as a person#

A key or an agent acts as the person who created it, with that person’s current role in the workspace. If the person leaves the workspace their keys and OAuth codes are revoked. If their role is reduced, the credential loses the same abilities at once.

Role	Read	Edit and write	Approve, connections, Beats, webhooks	Create a key
Owner	yes	yes	yes	yes, including one for the whole workspace
Editor	yes	yes	yes	yes, for a site
Writer	yes	yes	no	yes, for a site
Viewer	yes	no	no	no

Approval is separate from all of this. Owner and Editor can approve in the interface; no credential can.

Scopes narrow a role#

Scopes are checked first, then the role. A scope can never grant what the role does not allow, and a role never grants what the scope does not carry.

Scope	Lets a credential	Never
`brief`	Create and change briefs, estimate them, check a topic.	Spend credits.
`generate`	Start an article from a brief, write a column.	Approve.
`read`	List and read articles and sites, read columns and house style, follow a job’s event stream.	Change anything.
`edit`	Add sources, rewrite, hand-edit, change structure, archive, steer jobs, re-read a site, regenerate an illustration.	Keep a flag, approve, comment.
`export`	Render exports and download them, deliver an approved article to the site’s connection.	Approve.

The two refusals#

Answer	Means
403 `scope_missing`	The credential does not carry the scope the route needs.
403 `key_not_allowed`	The route is not on the list a key may call. It stays with a person, whatever the scopes.
403 `human_only`	The route is open to a bearer but this action needs a signed-in person.
403 `forbidden`	The scope is right but the creator’s role does not allow it.

Site binding#

A key or an agent is bound to one site or, for a key an Owner makes, to the whole workspace. An agent is always bound to one site. A site-bound credential cannot see articles or briefs that belong to no site. Scopes and the site are fixed when the credential is made; to change them make a new one. Only the name and the daily cap can be edited.