Scopes

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. Grant exactly those and no more.

The full catalogue

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.

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.

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).

Scope	Lets a key
`tables:read`	List your project’s own tables and read their columns and rows.
`tables:write`	Insert, update, and delete rows in your project’s own tables.

Scope	Lets a key
`media:read`	List the project’s media assets and mint short-lived signed URLs for their bytes.
`media:write`	Upload new media assets and delete existing ones.

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.

That’s 21 scopes in total.

media:read doesn’t reach your customers’ files. Media a customer sent in over WhatsApp is returned only when a key holds conversations:read as well and explicitly asks for it. A media-only key sees the project’s own uploads and nothing else. See Storage.

The table scopes reach your tables only. Paige’s own platform tables — contacts, conversations, messages, execution logs, and broadcast recipients — are not addressable through /v1/tables, whatever scopes the key holds. Read those through their own endpoints instead, where the rules that protect them still apply. A write must also always carry a filter, so there is no way to accidentally update or delete a whole table in one call.

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.

When a scope is missing

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

{
  "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.

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.

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. 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`
A catalogue sync that uploads images and documents the bot sends	`media:read`, `media:write`
An event consumer	`webhooks:manage` plus each `events:*` you subscribe to

Getting started

Endpoints

The full catalogue

When a scope is missing

Two things that catch people out

Picking scopes for a job

​The full catalogue

​When a scope is missing

​Two things that catch people out

​Picking scopes for a job

The full catalogue

When a scope is missing

Two things that catch people out

Picking scopes for a job