Authorization and scope

Every authenticated API request must include valid credentials (API key or OAuth token). The credentials must have the appropriate scope for the specific endpoint being called.

API scopes

A scope is an additional layer of control and security over the REST API that limits what the endpoint users, API key, or OAuth clients are allowed to call.

Scopes provide access to a specific set of API endpoints, typically designed to serve specific use cases. Through OAuth2, they define the specific actions that applications are permitted to do on behalf of a user.

Benefits of the API scope

By granting a specific API scope to a user or an API key, you limit their access to a subset of API endpoints covered by the scope. This way you can prevent the user from accessing data or API functionalities outside of their role. You can limit the potential negative impact of leaked or stolen API keys or user credentials. You can grant several scopes to the same user or same API key, covering multiple different API endpoints needed for a complex use case.

API scope types

Scopes follow a consistent naming pattern: product:resource:action (for example, sms:message:send). Understanding the pattern helps you identify the right scope without looking up every one individually.

:manage is generally the broadest scope for a given channel or product. It covers all associated endpoints — sending traffic, reading logs, managing inbound messages, and configuration. Use it when your integration needs full access to a channel, but prefer narrower scopes where possible to limit exposure if a key is compromised.

:send covers outbound traffic for a channel. Use this when your integration only needs to send messages and has no reason to access logs, inbox, or configuration endpoints.

:read and :logs:read cover read-only access to data such as delivery logs and inbound messages, without any ability to send or configure.

The number of scopes available for a given channel depends on the product's complexity and the variety of use cases it supports. You can see all available scopes in the Available API scopes table below.

SDK scopes

These specific SDK scopes: web:sdk, mobile-app-messaging:sdk, 2fa:sdk, web:tracking:sdk are listed for backwards compatibility and cover specific use cases where the SDK runs in an end user's browser or mobile device, rather than server-side. Only assign these to keys used in client-side contexts.

API scope configuration

Each API endpoint requires at least one specific scope. You can find the required scopes listed in the documentation for each endpoint. Your API key only needs to have one of the listed scopes to access that endpoint.

Assign scopes when creating an API key

You can create a scoped API key through the web interface or the API.

Infobip web interface

Navigate to Developer Tools → API Keys → Create API key. Set the key name, expiration date, and optionally restrict it to specific IP addresses. Then, under API Scopes, expand the relevant category and select the scopes you need.

API

Use the Create API key endpoint and include your scopes in the scopeGuids array. If you omit scopeGuids from the request, the key will inherit all scopes granted to your user role. This behavior exists for backwards compatibility, but it's a good practice to always define an explicit, minimal set of scopes. Note that scopeGuids cannot be set to an empty list; the API will reject the request otherwise.

Update scopes on an existing API key

You can add or remove a scope for an already existing API key.

Infobip web interface

Edit the key through Developer Tools → API Keys. Click on the key you want to edit, change the scope, and click Save.

API

Use the Update API key endpoint and pass the full list of scopes you want the key to have. Scopes don't merge. The request replaces the existing scope list entirely, so omitting a scope will remove it.

The request only updates the top-level properties you include in the body; if you omit scopeGuids, existing scopes remain unchanged.

Available API scopes

The table below outlines the scopes currently used by the API platform.

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, scopes are granted implicitly through user roles. The user whose credentials you are using must have a role that includes the scopes required by the endpoints you are calling.

To check which scopes a role grants, see the table below. To assign a role to a user, see Manage roles.