Scopes
A scope says what a token may be used for. Ask only for the scopes your app needs: the consent screen lists each one in plain words.
Effective access is always the token’s scopes ∩ what the caller may do now. A scope never lifts a role, and a role never lifts a scope. For a person, that is their current role, checked on every request. For a machine client, it is the client’s acting role (never admin) and its library restriction, if any.
A call without the scope it needs answers 403 INSUFFICIENT_SCOPE with error.scope and WWW-Authenticate: Bearer error="insufficient_scope", scope="…". A call your role does not allow answers 403 FORBIDDEN.
| Scope | What the consent screen says | Lowest role | Machine clients |
|---|---|---|---|
assessments:read | Read questionnaires and their answers | User | Yes |
assessments:write | Upload questionnaires and start AI drafting (uses your organization's AI budget) | User | Yes |
questions:write | Edit answers during review | Reviewer | Yes |
assessments:review | Send questionnaires to Finalize on your behalf | Reviewer | No (people only) |
assessments:finalize | Finalize questionnaires on your behalf — their answers become approved knowledge | Approver | No (people only) |
knowledge:read | Read approved answers and their sources | User | Yes |
knowledge:ask | Ask questions — answers may be composed by AI from approved answers and use your organization's AI budget | User | Yes |
knowledge:gaps | See questions without approved answers | User | Yes |
knowledge:propose | Propose answers for review — nothing becomes an approved answer until an approver accepts it | User | Yes |
review:read | See the knowledge review queue | Reviewer | Yes |
library:write | Add documents to your knowledge libraries | Reviewer | Yes |
documents:download | Download your organization's source documents | User | Yes |
audit:read | Read your organization's audit log | Admin | Only with an admin's explicit grant |
Operations by scope
Section titled “Operations by scope”assessments:read: List questionnaires (GET), One questionnaire (GET), Its questions and answers (GET), Download the completed file (GET)assessments:write: Upload a questionnaire (POST), Analyze (step 1 of 4) (POST), Process (step 2 of 4) (POST)questions:write: Edit an answer during review (PATCH), Queue a new draft for one question (POST)assessments:review: Send to Finalize (step 3 of 4) (POST)assessments:finalize: Finalize (step 4 of 4) (POST)knowledge:read: Approved answers (GET), One approved answer (GET), Libraries (GET), One library (GET), Topics (GET), Documents (GET), One document (GET), Knowledge health (GET)knowledge:ask: Ask a security question (POST)knowledge:gaps: Knowledge gaps (GET)knowledge:propose: Propose an answer (POST), Propose an edit (POST), Answer a knowledge gap (POST)review:read: The knowledge review queue (GET), A proposal or conflict side by side (GET)library:write: Add a document or a Q&A (POST), Upload a new version (POST)documents:download: Download a document file (GET)audit:read: Audit events (SIEM export) (GET)
GET /v1/me works with any valid token, and GET /v1/openapi.json needs none. These lists and the reference are generated from the same OpenAPI description.
knowledge:proposealso needs the role permission Propose answers from apps and AI tools; proposing an edit to an existing answer needs a reviewer. Whatever the role, proposals always wait for an approver.assessments:reviewandassessments:finalizeare for people only. A machine client cannot hold them.assessments:finalizeandaudit:readare sensitive: the consent screen warns about them and needs a sign-in in the last 12 hours.audit:readis the one admin-level scope. A machine client gets it only when an admin ticks it explicitly for that client.- Operations that use AI (
POST /v1/ask, Process, regenerate) spend your organization’s AI budget. - When a person’s role is lowered, their connections keep only the scopes the new role allows.
Four scopes are shared with AI tools (MCP): knowledge:read, knowledge:ask, knowledge:gaps and knowledge:propose. A token is issued for either the API or MCP, never both.
Scopes are never removed from /v1. New scopes can be added (see Versioning).