# 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](https://www.infobip.com/docs/developer-resources/authentication-and-access/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.

Web interface

1. Go to **Developer Tools** > **API Keys** > [**Create API key**](https://portal.infobip.com//dev/api-keys).
2. Set the key name and expiration date.
3. Optionally, add allowed IP addresses to restrict usage to specific sources.
4. Under **API Scopes**, expand the relevant category and select the scopes you need.
5. 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

API

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](https://www.infobip.com/docs/developer-resources/authentication-and-access/api-authentication#basic-authentication), [OAuth 2.0](https://www.infobip.com/docs/developer-resources/authentication-and-access/api-authentication#oauth-20-authentication), or an [IBSSO token](https://www.infobip.com/docs/developer-resources/authentication-and-access/api-authentication#ibsso-token-authentication). The following example uses Basic authentication and creates a key that can send SMS messages and read SMS logs until the date in `validTo`:

```bash
curl -X POST 'https://{baseUrl}/settings/2/api-keys' \
    -H 'Authorization: Basic {base64-encoded-credentials}' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
        "name": "SMS integration",
        "validTo": "2027-10-01T00:00:00",
        "scopeGuids": ["sms:message:send", "sms:logs:read"]
    }'
```

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](https://www.infobip.com/docs/api/platform/account-management/api-keys/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](#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](https://www.infobip.com/docs/cpaas-x/security/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.

IMPORTANT
Removing a scope from a key that is actively in use immediately disrupts any traffic or functionality that depends on it. Confirm which integrations rely on the scope before you update the key.

Web interface

Go to **Developer Tools** > [**API Keys**](https://portal.infobip.com//dev/api-keys). Select the key, change the scopes, and select **Save**.

API

Use the [Update API key](https://www.infobip.com/docs/api/platform/account-management/api-keys/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.

NOTE
The request only updates the top-level properties you include in the body. If you omit `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](https://www.infobip.com/docs/developer-resources/authentication-and-access/api-scopes-reference#user-roles-and-api-scopes) in API scopes reference. To assign a role to a user, see [Manage roles](https://www.infobip.com/docs/get-started/account-settings/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](https://www.infobip.com/docs/developer-resources/authentication-and-access/api-authentication#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.

```json
{
  "errorCode": "E403",
  "description": "Insufficient permissions to access the requested resource.",
  "action": "Repeat the request with new or different credentials.",
  "violations": [],
  "resources": [
    {
      "name": "API Scopes",
      "url": "/docs/developer-resources/authentication-and-access/authorization-and-scopes#api-scopes"
    }
  ]
}
```

Some endpoints can return a previous version of the error:

```json
{
    "requestError": {
        "serviceException": {
            "messageId": "FORBIDDEN",
            "text": "Forbidden"
        }
    }
}
```

For all HTTP status codes and how to handle them, see [Handling errors](https://www.infobip.com/docs/developer-resources/api-fundamentals/handling-errors).

___

Related pages

[API scopes reference](https://www.infobip.com/docs/developer-resources/authentication-and-access/api-scopes-reference)
All available API scopes and the scopes granted by predefined user roles.

[API authentication](https://www.infobip.com/docs/developer-resources/authentication-and-access/api-authentication)
Authenticate requests using API keys, OAuth 2.0, IBSSO tokens, or HTTP Basic authentication.

[Security best practices](https://www.infobip.com/docs/developer-resources/security/security-best-practices)
Guidelines for securing API integrations: authentication, traffic encryption, credential storage, and AIT prevention.