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

# Permissions

> The operation-scope model that controls which endpoints a key can call.

Every Public API key carries a list of **operation scopes**. Each endpoint requires one or
more scopes; calls without the right scope return `403 Forbidden` with
`{ "error": { "code": "FORBIDDEN", "message": "Operation not allowed" } }`.

## Scope naming

Scopes use the form `<resource>:<verb>`. The available scopes today:

| Scope                | What it allows                                                      |
| -------------------- | ------------------------------------------------------------------- |
| `conversation:read`  | `GET /v1/conversation/{id}` and `GET /v1/conversation/{id}/context` |
| `conversation:write` | `PATCH /v1/conversation/{id}`                                       |
| `client:read`        | All `GET` endpoints under `/v1/client`                              |
| `client:write`       | All `POST` and `PATCH` endpoints under `/v1/client`                 |
| `user:read`          | All `GET` endpoints under `/v1/user`                                |
| `site:read`          | All `GET` endpoints under `/v1/site`                                |
| `site:write`         | All `POST` and `PATCH` endpoints under `/v1/site`                   |

Each endpoint's required scope is also shown in the **API Reference** tab in the
"Required permissions" callout under the endpoint summary.

## Choosing scopes

When you create a key in **Settings → Integrations → Developer** (see
[Authentication](/authentication)), select the minimum set of scopes your integration
needs. Granting a parent resource also grants its children (for example, `client:read`
includes `clientEmail:read`).

## Updating scopes on an existing key

Open **Settings → Integrations → Developer**, choose the key, and select **Edit scopes**.
Saving updates the key's allowed operations without changing the secret value.