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; edit and publish their call flow
calls:read	List and fetch calls (including transcript and recording URL) and scheduled calls
calls:write	Place, schedule and cancel outbound calls; hang up a live call
nudges:read	List and fetch nudges, and preflight a number (a nudge’s recording, summary and extracted fields also need calls:read)
nudges:write	Create and cancel nudges (one by one or in bulk)
campaigns:read	List and fetch campaigns, their runs, progress and outcome board
campaigns:write	Create, update, and delete campaigns; set contacts; change status; start runs; move board cards
contacts:read	List and fetch contacts; read the do-not-call list
contacts:write	Create, update, and delete contacts; add numbers to the do-not-call list
contacts:erase	Permanently erase a contact’s personal data (DPDP) - irreversible, so grant it only where needed
numbers:read	List phone numbers
numbers:write	Choose which agent answers a number’s incoming calls
webhooks:read	List webhook endpoints and their delivery logs. Delivery logs include each event’s full payload - for call.* and nudge.* events that means call content such as the summary and extracted fields - so treat this scope like calls:read.
webhooks:write	Create, update, and delete webhook endpoints; rotate secrets; send test events; replay deliveries. A key that can point an endpoint anywhere receives every event payload, call content included.
knowledge:read	List knowledge bases, their documents, and search them
knowledge:write	Create and delete knowledge bases; add and remove documents
chat:read	Read chat sessions opened with the API, with their transcript
chat:write	Open chat sessions, send messages, and end sessions
whatsapp:read	List and fetch WhatsApp conversations and messages (customer numbers and message text included), download inbound media, list numbers and templates
whatsapp:write	Start and end WhatsApp conversations, send messages without an agent, and create, edit, delete, sync and upload samples for templates. Also needed (with campaigns:write) for any write to a WhatsApp campaign; whatsapp:read (with campaigns:read) shows its WhatsApp block and recipients
compliance:read	Verify and export the compliance decision log, and read blocked-call statistics (contains call-level personal data)
streams:read	List data streams and the records they received
streams:write	Create, change and delete data streams, push records into them, and attach them to campaigns
billing:read	Read the wallet balance, per-minute rate and transaction ledger

Buying and releasing phone numbers is console-only (Indian regulatory provisioning isn’t exposed on the API). numbers:write only routes a number you already own to an inbound agent.

Check your key

GET /v1/me  ·  any valid key

Returns the key you called with, what it may do, and its workspace. Useful as a health check in your integration.

{
  "data": {
    "key": { "id": "key_…", "name": "Production backend", "scopes": ["calls:read", "calls:write"], "prefix": "ohk_live_••••a1b2", "expiresAt": null },
    "workspace": { "id": "…", "name": "Acme Retail", "kybVerified": true }
  }
}

kybVerified must be true before calls can be placed.

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 and campaign runs.
• contacts:erase is the one exception: erasing a contact needs it explicitly.

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.
• React to calls in real time → webhooks:write to register an endpoint once (then events arrive on their own).
• Full automation → the read + write scopes for each resource you touch.

Next: Calls →