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