resource:action scope vocabulary. A personal access token or OAuth client is granted a set of these, and each endpoint lists the scope it requires under its Authorizations.
The vocabulary
| Scope | Grants |
|---|---|
conversations:read | Read your conversations and their messages |
conversations:write | Start conversations and send messages on your behalf |
documents:read | Read your documents library |
documents:write | Upload and manage documents in your library |
schedules:read | View your scheduled tasks |
schedules:write | Create and manage scheduled tasks |
agents:read | View the agents in your workspace |
agents:write | Create and configure agents |
memory:read | Read what the assistant remembers about you |
memory:write | Correct or delete what the assistant remembers |
billing:read | View usage and billing information |
admin | Administer the workspace — users, settings, integrations, audit |
How scopes resolve
- A token never exceeds its user’s role. The effective permissions are the user’s role capabilities intersected with the token’s granted scopes. A non-admin’s token that asks for
adminis silently clamped — never escalated. adminis role-gated. Only a user with the admin role can hold it. An admin token can do everything a member token can, plus workspace administration.- Request least privilege. Ask only for the scopes you use. For OAuth, the granted set is your request intersected with the client’s allowed scopes; requesting only scopes the client isn’t allowed yields
invalid_scope. - Unknown scopes are ignored (forward-compatible) — a scope added later won’t break an existing token.
Legacy coarse tiers still work:
user (or integrator) grants every non-admin scope; admin grants everything. New integrations should use the explicit resource:action scopes above.