Scopes

Every API key carries a set of scopes. Each endpoint requires exactly one scope; a key without it is rejected with 403. Scopes are <resource>:<action>.

Grant each key the narrowest set for its job - a reporting integration that only reads calls needs calls:read, not calls:write.

Catalog

Scope	Grants
agents:read	List and fetch agents
agents:write	Create, replace, publish/unpublish, and delete agents
calls:read	List and fetch calls, including transcript and recording URL
calls:write	Place an outbound call
campaigns:read	List and fetch campaigns and their runs
campaigns:write	Create, update, and delete campaigns; set contacts; change status; start runs
contacts:read	List contacts
contacts:write	Create, update, delete, and erase contacts
numbers:read	List phone numbers

Buying and releasing phone numbers is console-only (Indian regulatory provisioning isn’t exposed on the API), so there is no writable numbers endpoint.

Which scope an endpoint needs

Each reference page states the scope in the endpoint heading. As a rule:

• :read scopes cover the GET endpoints for that resource.
• :write scopes cover POST, PUT, and DELETE for that resource - including status changes, erasure, and campaign runs.

Choosing scopes

A few common shapes:

• Place calls from your app → calls:write (+ calls:read to read results).
• Sync results into your data warehouse → calls:read, campaigns:read.
• Manage agents in code → agents:read, agents:write.
• Full automation → the read + write scopes for each resource you touch.

Next: Calls →