Scopes & permissions

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 shows the scope it requires.

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

{ "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, 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`

Get started

Concepts

Guides

How scopes combine

All scopes

Keys without scopes

Scopes a key can never have

Actions keys can never take

Stricter permissions for keys

Choosing scopes

​How scopes combine

​All scopes

​Keys without scopes

​Scopes a key can never have

​Actions keys can never take

​Stricter permissions for keys

​Choosing scopes

How scopes combine

All scopes

Keys without scopes

Scopes a key can never have

Actions keys can never take

Stricter permissions for keys

Choosing scopes