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

# Scopes & permissions

> What an API key is allowed to do, and the permissions it can never have.

An API key carries a list of **scopes**. Scopes are the same permission names your dashboard roles use, so a key
with `campaigns.edit` can do what a teammate with "Campaigns: Edit / run" can do.

## How scopes combine

* **`edit` and `delete` include `view`.** A key with `agents.edit` can also read agents.

* **Some special scopes include others:**

  | Scope | Also grants |
  | - | - |
  | `calls.test` | `calls.view`, `agents.view` |
  | `whatsapp.send` | `whatsapp.view` |
  | `speech.upload` | `speech.view` |
  | `workflows.run` | `workflows.view` |
  | `workflows.recover` | `workflows.view` |
  | `team.manage` | `team.view` |
  | `billing.recharge` | `billing.view` |

* **A key never exceeds the member it acts for.** Its effective permissions are its scopes intersected with that
  member's current role. Narrowing the member's role narrows the key from the next request.

* Each endpoint page in the [API reference](/api-reference/introduction) shows the scope it requires.

When a key lacks a permission, the request fails with:

```json theme={null}
{ "error": "forbidden", "requiredPermission": "campaigns.edit" }
```

## All scopes

| Area | Scope | Allows |
| - | - | - |
| Analytics | `analytics.view` | Dashboards, funnels and reports. |
| Business intelligence | `intel.view` | Campaign lead intelligence, exports and live sheets. Also needs a plan that includes business intelligence. |
| Speech analysis | `speech.view` | Read scored analyses of your reps' calls. |
| | `speech.edit` | Manage reps and teams. |
| | `speech.delete` | Delete analyses, reps and teams. |
| | `speech.upload` | Upload recordings for analysis. **Billed per analysis.** |
| Campaigns | `campaigns.view` | Read campaigns, contacts, stats and results. |
| | `campaigns.edit` | Create, edit and run campaigns (start, pause, resume, stop), add contacts. |
| | `campaigns.delete` | Delete campaigns, clear contacts, detach phone numbers, cancel queued retries. |
| Calls | `calls.view` | Read calls, transcripts and recordings. |
| | `calls.edit` | Re-run extraction and evaluation, add numbers to Do Not Call. |
| | `calls.test` | Place test calls and web test sessions. **Billed.** |
| Sales | `sales.view` | Attributed orders and revenue (commerce analytics). |
| Workflows | `workflows.view` | Read workflows and runs. |
| | `workflows.run` | Start and cancel workflow runs. |
| | `workflows.recover` | Resolve workflow runs that need manual recovery. |
| Agents | `agents.view` · `agents.edit` · `agents.delete` | AI calling agents and their configuration. |
| Agent documents | `knowledge.view` · `knowledge.edit` · `knowledge.delete` | Documents linked to agents. |
| Dictionaries | `dictionaries.view` · `dictionaries.edit` · `dictionaries.delete` | Pronunciation and recognition word lists. |
| Custom functions | `functions.view` · `functions.delete` | Webhook tools bound to agents. |
| Background audio | `background_audio.view` · `background_audio.edit` · `background_audio.delete` | Ambient audio assets for agents. |
| Campaign templates | `campaign_types.view` · `campaign_types.edit` · `campaign_types.delete` | Reusable campaign types and their extraction fields. |
| Chatbots | `chatbots.view` · `chatbots.edit` · `chatbots.delete` | Embeddable chatbots, their knowledge bases and conversation logs. |
| CRM connections | `crm.view` · `crm.edit` · `crm.delete` | CRM connectors, field mappings, syncs and imports. |
| Integrations | `integrations.view` · `integrations.edit` · `integrations.delete` | Tool integrations bound to agents. |
| Calendar booking | `calendar.view` · `calendar.edit` | Calendar connection settings and booked appointments. |
| WhatsApp | `whatsapp.view` | Senders, templates, conversations and message history. |
| | `whatsapp.edit` | Manage senders, templates and media collections. |
| | `whatsapp.delete` | Disconnect senders, delete templates and media. |
| | `whatsapp.send` | Send messages. **Billed per message.** |
| Phone numbers | `phone_numbers.view` · `phone_numbers.edit` | Your numbers and their inbound-agent routing. |
| Billing | `billing.view` | Wallet balance, ledger and receipts. |
| API keys | `api_keys.view` | List the workspace's API keys (never their secrets). |
| Result webhooks | `result_webhooks.view` · `result_webhooks.delete` | Read and delete result webhook endpoints and deliveries. |
| Workspace | `workspace.view` | Read workspace settings. |
| Team | `team.view` | Read members, roles and the permission catalog. |

## Keys without scopes

Keys issued before scopes were introduced carry no scopes. They keep full access to the
[`/v1` endpoints](/api-reference/introduction#public-api-v1), with no scope checks, and every other endpoint refuses
them with `403 api_key_not_scoped`. To use the rest of the API, ask Pineyard for a key with scopes.

## Scopes a key can never have

These stay with people signed in to the dashboard. A key is never issued with them, and a key that somehow holds
one does not get it.

| Scope | Why |
| - | - |
| `api_keys.edit`, `api_keys.delete` | A key could create or keep keys for itself. |
| `team.manage` | A key could change who has access. |
| `workspace.edit` | Workspace-level configuration. |
| `billing.recharge` | Top-ups are payments a person completes in a browser. |
| `result_webhooks.edit` | Changing where results are delivered must be done by a person. |
| `workflows.edit` | An active workflow can send data to any address on every trigger. |
| `functions.edit` | A custom function sends call data and stored headers to its address on every call. |

## Actions keys can never take

Some endpoints act as a specific person or need a browser, so they refuse API keys with
`403 api_key_not_allowed` whatever the scopes:

* signing in to third-party services (calendar, sheets, CRM and integration connections),
* WhatsApp sender signup and QR connection, and reserving WhatsApp numbers,
* buying phone numbers and identity verification,
* wallet top-ups and payment details,
* removing a number from the Do Not Call list,
* chatbot test chats,
* editing the shared home dashboard,
* reading or attaching arbitrary spreadsheets,
* personal profile, onboarding and notifications,
* all email features, including creating, starting or resuming a campaign whose channel is `EMAIL`.

## Stricter permissions for keys

A few endpoints sit behind a `view` permission in the dashboard but change data. API keys need the stronger
permission shown here. The `403` names it in `requiredPermission`.

| Endpoint | Dashboard permission | API keys need |
| - | - | - |
| `POST /calls/{id}/transcript-translation` | `calls.view` | `calls.edit` |
| `POST /calls/{id}/issues` | `calls.view` | `calls.edit` |
| `DELETE /campaigns/{id}/chat/messages` | `intel.view` | `campaigns.delete` |
| `POST /campaigns/{id}/import-from-crm` | `crm.edit` | `campaigns.edit` |
| `POST /campaigns/{id}/sheet` | `intel.view` | `campaigns.edit` |
| `POST /campaigns/{id}/sheet/sync` | `intel.view` | `campaigns.edit` |
| `PATCH /campaigns/{id}/sheet` | `intel.view` | `campaigns.edit` |
| `POST /campaigns/{id}/sheet/rebuild` | `intel.view` | `campaigns.edit` |
| `DELETE /campaigns/{id}/sheet` | `intel.view` | `campaigns.delete` |
| `DELETE /knowledge-bases/{id}/documents/{docId}` | `chatbots.edit` | `chatbots.delete` |
| `POST /whatsapp/templates/{id}/sync-status` | `whatsapp.view` | `whatsapp.edit` |
| `POST /whatsapp/conversations/{id}/archive` | `whatsapp.view` | `whatsapp.edit` |
| `POST /whatsapp/conversations/{id}/unarchive` | `whatsapp.view` | `whatsapp.edit` |
| `PUT /whatsapp/campaigns/{id}` | `whatsapp.edit` | `campaigns.edit` |

## Choosing scopes

| Your integration | Ask for |
| - | - |
| Manage agents and run campaigns | `agents.edit`, `agents.delete`, `campaigns.edit`, `campaigns.delete`, `phone_numbers.view`, `calls.view` |
| Run campaigns with existing agents | `agents.view`, `campaigns.edit`, `phone_numbers.view`, `calls.view` |
| Read-only reporting | `campaigns.view`, `calls.view`, `analytics.view` |
| Push leads into a campaign and collect results (`/v1`) | `campaigns.edit` (push) and `campaigns.view` (results) |
| Place test calls | add `calls.test` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.