Scopes

Every route needs a scope; a token carries only the ones it was granted.

Scope	What it opens	Third-party apps
`users:read`	See the people in your company	at once
`users:write`	Change people's names, extensions and roles	at once
`numbers:read`	See your phone numbers	at once
`numbers:write`	Assign your phone numbers	at once
`devices:read`	See your phones and apps	at once
`devices:write`	Manage your phones and apps	at once
`calls:read`	Read your call history	at once
`calls:write`	Place calls as you	at once
`calls:control`	Hold, transfer, record and hang up your live calls	needs approval
`recordings:read`	Listen to your call recordings	needs approval
`transcripts:read`	Read your call transcripts	needs approval
`presence:read`	See who is available	at once
`presence:write`	Change your status and do-not-disturb	at once
`messages:read`	Read your text messages	at once
`messages:write`	Send text messages as you	at once
`voicemails:read`	Listen to your voicemails	at once
`voicemails:write`	Mark and delete your voicemails	at once
`faxes:read`	See your faxes	at once
`faxes:write`	Send faxes as you	at once
`webhooks:manage`	Be told when calls and messages happen	at once
`account:read`	See your company's name and plan	at once

Scopes marked needs approval touch what a person says on the phone: controlling a live call, listening to a recording, reading a transcript. An API key of your own company gets them at creation; an OAuth app used in a company other than the one that registered it must request them first (Developer → Apps → Request) and be approved by AIMERICA. Until then /oauth/authorize refuses those scopes with error=invalid_scope.

Each route names its scope in the reference (x-scope). A request without it answers 403 insufficient_scope:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="calls:read"
{"error": {"type": "insufficient_scope", "message": "This token does not have the calls:read scope", "request_id": "…"}}

Keys created before 25 September 2026 keep their old names (calls:read, calls:write, messages:read, messages:write, numbers:read, contacts:read, contacts:write); the first five are accepted as they are by API v1, contacts stay on the app's older API.