> For the complete documentation index, see [llms.txt](https://docs.guayaba.run/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.guayaba.run/documentation/api-reference/key-types-and-scopes.md).

# Key Types & Scopes

#### Master Key (`g_master_`)

* One per user. Creating a new one revokes the previous (and cascade-revokes all agent keys).
* Full access to all endpoints and all agents owned by the user.

#### Agent Key (`g_agent_`)

* One per agent. Tied to a single agent by `agent_id`.
* Cannot access other agents (returns `403`).
* Access controlled by **scopes** assigned at creation time.

#### Scopes

| Scope          | Description                                              | Default         |
| -------------- | -------------------------------------------------------- | --------------- |
| `agent:read`   | View agent details and status                            | Always included |
| `agent:manage` | Start, stop, pause, reload. Manage sessions and archives | No              |
| `channels`     | Manage Telegram pairing (list, approve, revoke, reject)  | No              |
| `files`        | Upload files to the agent                                | No              |
| `chat`         | Send messages to the agent via API                       | No              |

A master key implicitly has all scopes.
