Authorization and scopes
Every authenticated API request needs credentials that carry the scope the endpoint requires. An API key carries the scopes assigned to it. With other authentication methods, the roles of the user determine the scopes.
API scopes
A scope is an additional layer of control and security over the REST API. It limits which endpoints an authenticated user, API key, or OAuth client can call. Scopes provide access to a specific set of API endpoints, typically designed to serve specific use cases.
By granting a specific scope to a user or an API key, you can:
- Limit their access to a subset of API endpoints covered by the scope
- Prevent users from accessing data or API functionality outside their role
- Reduce the potential negative impact of leaked or stolen API keys
- Combine multiple scopes on the same user or API key to cover the different endpoints a complex integration needs
Scope naming pattern [#scope-naming-pattern-api-scopes]
Scopes follow a consistent naming pattern: product:resource:action (for example, sms:message:send). In this example, sms is the product or channel, message is the resource being acted on, and send is the action. The action determines the level of access granted.
Understanding the pattern helps you identify the correct scope without checking every scope individually. The following table lists the common actions:
| Action | What it covers | When to use |
|---|---|---|
:manage | The broadest scope within a single channel or product. Covers all associated endpoints: sending traffic, reading logs, managing inbound messages, and configuration. | When your integration needs full access to one channel. Prefer narrower scopes where possible to limit exposure if a key is compromised. |
:send | Outbound traffic only. | When your integration only needs to send messages and has no reason to access logs, inbox, or configuration endpoints. |
:read and :logs:read | Read-only access to data such as delivery logs and inbound messages, without any ability to send or configure. | When your integration queries data only. |
:delete | Deletion of specific resources such as recordings. More targeted than :manage. | When your integration needs to delete specific resources but not configure or send. |
:receive | Inbound traffic only. Complement to :send. | When your integration only needs to handle incoming calls or messages, not send them. |
:record | Recording of calls or sessions. | When your integration needs to record traffic but not otherwise manage it. |
:use | Limited execute access. Use an existing resource without full management rights. | When your integration needs to trigger a resource (for example, add participants to a flow or submit data to a form) but not configure it. |
:view | View-only access, narrower than :read. Common in product-specific contexts. | When your integration needs visibility into a resource without being able to query raw data. |
:control | Launch, stop, or cancel a resource without the ability to edit it. | When your integration orchestrates existing flows or campaigns but does not need to configure them. |
:provision | Provisioning and setup actions, such as registering senders or numbers. | When your integration automates onboarding or resource setup. |
:sdk | Client-side SDK access (web:sdk, mobile-app-messaging:sdk, 2fa:sdk, web:tracking:sdk). Listed for backward compatibility. Applies only when the SDK runs in the browser or mobile device of an end user. | Only for keys used in client-side contexts. Do not assign to server-side integrations. |
The number of scopes available for a given channel depends on the complexity of the product and the variety of use cases it supports. Some product-specific actions exist beyond these patterns (for example, :query, :testing, :conversions). For the complete list, see API scopes reference.
General cross-channel scopes [#general-cross-channel-scopes-api-scopes]
Two general scopes span all channels and do not need to be specified per channel. The following table lists them:
| Scope | What it covers |
|---|---|
message:send | Enables sending of mobile terminated (MT) messages regardless of the channel. Includes all channel:message:send endpoints across all channels. |
inbound-message:read | Enables fetching of mobile originated (MO) messages regardless of the channel. Includes all channel:inbound-message:read endpoints across all channels. |
These cover sending and receiving across all channels with a single scope. Unlike :manage, they do not include channel configuration. Use them when your integration spans multiple channels and you only need to send or receive messages without configuring individual channels.
How scopes apply to endpoints [#how-scopes-apply-to-endpoints-api-scopes]
Each API endpoint requires at least one specific scope. Your API key only needs to have one of the listed scopes to access that endpoint. You do not need to assign every scope an endpoint lists.
To find the required scopes for a specific endpoint, go to the endpoint in the API reference. Check the Scopes field, listed next to Authorizations on the endpoint page. Each endpoint lists the exact scopes it accepts (for example, message:send).
Assign scopes when creating an API key
Only users with the Account admin or Channel setup and integrations role can create API keys. You can only assign scopes your own user role has.
- Go to Developer Tools > API Keys > Create API key.
- Set the key name and expiration date.
- Optionally, add allowed IP addresses to restrict usage to specific sources.
- Under API Scopes, expand the relevant category and select the scopes you need.
- Select Create, then copy the key and store it securely.
The web interface offers the following scope categories:
- General: Cross-channel scopes (for example,
message:send,inbound-message:read) - Channels: Per-channel scopes (SMS, Email, WhatsApp, Voice, and more)
- Connectivity: Number lookup, Mobile Identity, Number Activation State
- Platform: Account management, Messages API, Subscriptions, Signals, Blocklist
- Customer Engagement: Conversations, People, Answers, Moments flows, Forms
- Client-side SDK: Client-side SDK scopes
Use POST /settings/2/api-keys to create an API key, and define an explicit, minimal set of scopes in the scopeGuids array. If you omit scopeGuids, the key inherits all scopes granted to your user role. The scopeGuids array cannot be empty. If it is, the API rejects the request.
The API key endpoints do not accept an API key. Authenticate the request with Basic authentication, OAuth 2.0, or an IBSSO token. The following example uses Basic authentication and creates a key that can send SMS messages and read SMS logs until the date in validTo:
The response includes an apiKeySecret field (the actual key value). You can view and copy the key for a limited time only, so store it securely right away.
For the full request schema, see the Create API key endpoint in the API reference. If the request returns 403, your role does not include the scopes you are trying to assign. See Authorization errors.
If you are managing messaging for multiple customers or brands, API keys can also be scoped to specific Applications and Entities. See Manage API keys in the CPaaS X docs.
Update scopes on an API key
You can change the scopes on an existing API key in the web interface or through the API.
Go to Developer Tools > API Keys. Select the key, change the scopes, and select Save.
Use the Update API key endpoint and pass the full list of scopes you want the key to have. Scopes do not merge. The request replaces the existing scope list entirely. Omitting a scope from the scopeGuids array removes it. You cannot send scopeGuids and platform (CPaaS X Applications and Entities) in the same request.
scopeGuids entirely, the scopes on the key remain unchanged. The API rejects an empty scopeGuids array, so a key always has at least one scope.User roles and API scopes
If you are using Basic authentication instead of an API key, scopes are not assigned directly to the user. Instead, user roles grant scopes implicitly. For the full role-to-scope mapping and role capability descriptions, see User roles and API scopes in API scopes reference. To assign a role to a user, see Manage roles.
Authorization errors
A 403 Forbidden response means your credentials are valid, so authentication succeeded. Your API key or user role does not have the required scope for the endpoint you are calling. This is distinct from 401 Unauthorized, which means authentication itself failed. See Authentication errors for 401 error handling.
To fix a 403, check the Scopes field of the endpoint in the API reference, and add one of the listed scopes to your API key or a role with that scope to your user.
Some endpoints can return a previous version of the error:
For all HTTP status codes and how to handle them, see Handling errors.
API scopes reference
All available API scopes and the scopes granted by predefined user roles.
API authentication
Authenticate requests using API keys, OAuth 2.0, IBSSO tokens, or HTTP Basic authentication.
Security best practices
Guidelines for securing API integrations: authentication, traffic encryption, credential storage, and AIT prevention.
Was this page helpful?