> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hq.zone/llms.txt
> Use this file to discover all available pages before exploring further.

# Scopes

> The resource:action permission vocabulary that tokens and OAuth clients grant from.

HQ uses a `resource:action` scope vocabulary. A [personal access token](/get-started/authentication) or [OAuth client](/guides/oauth) 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 `admin` is silently clamped — never escalated.
* **`admin` is 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.

<Note>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.</Note>