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

# Scopes

> Each API key carries a set of scopes, and every endpoint requires one. Grant the minimum a key needs — a key missing a required scope gets 403 insufficient_scope.

A scope is a single permission. You tick scopes when you create a key under **Settings → API → API Keys**, and you can edit them afterwards without issuing a new key.

Every endpoint states the scope it needs, both in its description and in the `x-required-scopes` field of the [OpenAPI document](https://api.paigeme.dev/v1/openapi.json). Grant exactly those and no more.

## The full catalogue

<Tabs>
  <Tab title="Messaging">
    | Scope                 | Lets a key                                                                                                           |
    | --------------------- | -------------------------------------------------------------------------------------------------------------------- |
    | `messages:send`       | Send WhatsApp session and template messages.                                                                         |
    | `conversations:read`  | List conversations and read their messages and delivery status.                                                      |
    | `conversations:write` | Change a conversation's state — `handover`, `unstructured`, `awaiting_form`, `done`, or any state your own bot uses. |
    | `contacts:read`       | Read contact records.                                                                                                |
    | `contacts:write`      | Update a contact's name, tags, and custom attributes.                                                                |
  </Tab>

  <Tab title="Templates & broadcasts">
    | Scope               | Lets a key                                                                                                                                        |
    | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `templates:read`    | List message templates and their approval status.                                                                                                 |
    | `templates:manage`  | Create and delete WhatsApp message templates.                                                                                                     |
    | `broadcasts:read`   | View broadcast campaigns and their status.                                                                                                        |
    | `broadcasts:manage` | Create and assemble broadcast campaigns, and define the segments they target. **It never sends one** — every campaign is held for human approval. |
  </Tab>

  <Tab title="Code & flows">
    | Scope         | Lets a key                                                           |
    | ------------- | -------------------------------------------------------------------- |
    | `code:read`   | List and read the project bot code files.                            |
    | `code:write`  | Edit project code files and deploy dev → production.                 |
    | `flows:read`  | List WhatsApp Flows and read a flow's JSON definition.               |
    | `flows:write` | Generate and update WhatsApp Flows (routed through the flows agent). |
  </Tab>

  <Tab title="Webhooks & events">
    | Scope                     | Lets a key                                                 |
    | ------------------------- | ---------------------------------------------------------- |
    | `webhooks:manage`         | Register and manage outbound webhook subscriptions.        |
    | `events:message_received` | Deliver a webhook when an inbound message arrives.         |
    | `events:message_status`   | Deliver a webhook when a message delivery status changes.  |
    | `events:template_status`  | Deliver a webhook when a template approval status changes. |
  </Tab>
</Tabs>

That's 17 scopes in total.

<Warning>
  **`broadcasts:manage` is not a licence to send.** `POST /v1/broadcasts` always lands the campaign in `pending_approval`, whatever scopes the credential holds. There is no send, launch, approve, or retry endpoint — a human releases the campaign from the **Broadcasts** tab in the dashboard. Don't design a flow that expects the API to send; it never will. See [Broadcasts](/guides/broadcasts).
</Warning>

## When a scope is missing

A valid key calling an endpoint it isn't scoped for gets:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "insufficient_scope",
    "message": "…"
  },
  "request_id": "8f1c…"
}
```

with HTTP **403**. Fix it by editing the key's scopes in **Settings → API** — you don't need a new key.

<Tip>
  `GET /v1/ping` echoes back the scopes the credential actually holds. When a call 403s unexpectedly, ping first and compare against the endpoint's `x-required-scopes` before changing anything else.
</Tip>

## Two things that catch people out

**`webhooks:manage` isn't enough on its own.** Registering a webhook always needs `webhooks:manage`, but *subscribing to a platform event* also needs that event's own `events:*` scope. Asking for `message.received` without `events:message_received` fails with `403 insufficient_scope` at registration time, not at delivery time. Custom events your own bot emits need only `webhooks:manage`. See [Webhooks](/api-reference/webhooks).

**Scopes don't pool across projects.** If an AI agent is connected to several projects at once, each project carries its own grant. Being allowed to edit code in one project never implies it in another — the check runs against the selected project only.

## Picking scopes for a job

| If you're building…                                          | Grant                                                           |
| ------------------------------------------------------------ | --------------------------------------------------------------- |
| Order notifications out of your own system                   | `messages:send`, plus `templates:read` if you look templates up |
| A shared inbox or CRM sync                                   | `conversations:read`, `contacts:read`, `contacts:write`         |
| A marketing campaign tool (a human still approves each send) | `broadcasts:manage`, `broadcasts:read`, `templates:read`        |
| An AI agent that edits your bot                              | `code:read`, `code:write`, `flows:read`, `flows:write`          |
| An event consumer                                            | `webhooks:manage` plus each `events:*` you subscribe to         |