DevelopersGet started
Scopes
A scope is one permission, like calls:read. You pick a key's scopes when you create it, and its tokens can do only what those scopes allow. A request without the right scope fails with 403 insufficient_scope, whatever else the key can do.
On this page
Choosing scopes
- Start read-only. The Developers page has a Read-only preset; add
:writescopes only for what the app changes. - One key per job. A reporting script needs
calls:readandusage:read; a scheduling sync needsappointments:readandappointments:write. - Narrow a token further with the
scopeparameter when you ask for it (Authentication). A token never has a scope its key doesn't. - Keys can't be edited. To change scopes, create a new key and revoke the old one.
Account scopes
For keys created in a business's dashboard (direct AssistCall customers; a reseller's clients don't get keys). They reach that one account. Partner keys can hold them too, for the client named in the AssistCall-Account header.
account:readRead the account: name, time zone, status and plan.- GET/v1/account
calls:readRead calls, their summaries and transcripts.messages:readRead the messages the AI Employee took.messages:writeMark messages resolved, or open again.- PATCH/v1/messages/{id}
appointments:readRead appointments.appointments:writeBook, change and cancel appointments.contacts:readRead contacts.contacts:writeAdd and edit contacts.- POST/v1/contacts
- PATCH/v1/contacts/{id}
forms:readRead intake forms and the answers callers gave.knowledge:readRead packages and knowledge base articles.knowledge:writeAdd, edit and remove packages and articles.- POST/v1/knowledge
- PATCH/v1/knowledge/{id}
- DELETE/v1/knowledge/{id}
receptionists:readRead AI Employees and phone numbers.usage:readRead minutes and calls this billing period.- GET/v1/usage
webhooks:readRead webhook endpoints.webhooks:writeAdd, change, remove and test webhook endpoints.- POST/v1/webhooks
- PATCH/v1/webhooks/{id}
- DELETE/v1/webhooks/{id}
- POST/v1/webhooks/{id}/test
Partner scopes
Only keys created in the partner portal can have these. They work on the partner account itself, so they don't use the AssistCall-Account header. See Partner API.
partner:readRead your partner account.- GET/v1/partner
clients:readList your clients and read their status and usage.clients:writeCreate clients, resend invites, suspend, resume and change packages.- POST/v1/clients
- PATCH/v1/clients/{id}
- POST/v1/clients/{id}/invite
packages:readRead your packages.- GET/v1/packages
Endpoints without a scope
Any valid token can call these:
GET /v1/me: The key behind this tokenGET /v1/events/types: List webhook event types
Sandbox credentials
:read scope except webhooks:read (webhook URLs can contain their owners' own secrets). Every write is refused with 403 sandbox_read_only, even before scopes are checked.