# Permissions

> The scopes an API key can hold and what each one allows.

Each API key has an explicit list of scopes, chosen when you create it. Nothing is implied: a write scope does not include the matching read scope, so a key that replies to conversations and also reads them needs both `conversations:write` and `conversations:read`.

| Scope | Allows |
|---|---|
| `conversations:read` | List and read conversations and messages, internal notes included. |
| `customers:read` | List and read customers, including their email address. |
| `help-center:read` | List and read collections and articles (drafts too), and search published articles. |
| `feedback:read` | List and read boards, posts and comments. |
| `changelog:read` | List and read changelog entries. Drafts only when you ask for them. |
| `knowledge:read` | List the knowledge sources the AI agent learns from. |
| `credits:read` | Read the AI credit balance. |
| `ai:ask` | Ask the AI agent a question. |
| `conversations:write` | Reply to customers, add internal notes and close conversations. |
| `help-center:write` | Create article drafts. Never publishes. |
| `feedback:write` | Create feedback posts. |

## What each endpoint needs

| Endpoint | Scope |
|---|---|
| `GET /api/v1/workspace` | none, a valid key is enough |
| `GET /api/v1/conversations`, `/conversations/{id}`, `/conversations/{id}/messages` | `conversations:read` |
| `POST /api/v1/conversations/{id}/messages`, `/conversations/{id}/close` | `conversations:write` |
| `GET /api/v1/customers`, `/customers/{id}` | `customers:read` |
| `GET /api/v1/help-center/collections`, `/help-center/articles`, `/help-center/articles/{id}`, `/search` | `help-center:read` |
| `POST /api/v1/help-center/articles` | `help-center:write` |
| `GET /api/v1/feedback/boards`, `/feedback/posts`, `/feedback/posts/{id}` | `feedback:read` |
| `POST /api/v1/feedback/posts` | `feedback:write` |
| `GET /api/v1/changelog`, `/changelog/{id}` | `changelog:read` |
| `GET /api/v1/knowledge/sources`, `/knowledge/sources/{id}` | `knowledge:read` |
| `POST /api/v1/ask` | `ai:ask` |
| `GET /api/v1/credits` | `credits:read` |

## Two things to remember

- A key with `conversations:write` can send a message that customers read. When an action might reach a customer, the endpoint page says so. Give that scope only to code you trust.
- Articles you create through the API are always drafts. A person publishes them in Tirver.

If a key lacks the scope an endpoint needs, the API answers `403` with the code `insufficient_scope`, and the message names the scope. If a workspace has switched a module off, such as the help center, its endpoints answer `404` with `module_disabled`. See [errors](https://tirver.com/help/api/errors.md).

Source: https://tirver.com/help/api/permissions