API authorization

All authenticated API endpoints also require authorization. This is done by verifying whether the provided credentials, such as an API key or OAuth token, have at least one of the required API scopes. You can assign scopes to the API key as needed.

API scopes

A scope has become a standard term in the API environment. It originated in OAuth2 (opens in a new tab) specification, and the same idea is applied to all authentication types. It is an additional layer of control and security over the REST API that limits what the end-point 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.

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. In 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 API key, covering multiple different API endpoints needed for a complex use case.

API scope types

Various scope types exist depending on the area or context. The main scopes include:

1. General:

   • message:send
     • Enables sending of mobile terminated (MT) (opens in a new tab) messages, regardless of the channel
     • Includes all channel:message:send endpoints (all channels)
   • inbound-message:read
     • Enables fetching of mobile originated (MO) (opens in a new tab) messages, regardless of the channel
     • Includes all channel:inbound-message:read endpoints (all channels)
   • web:sdk
     • Provides access to People and People events API endpoints accessed from client-side SDK
   • mobile-app-messaging:sdk
     • Provides access to the Mobile App Messaging Mobile Push API endpoints accessed from the client-side SDK

2. product/channel:manage

   • Includes all endpoints related to a specific product or channel; e.g., if it is a Conversations product, it includes all endpoints related to Conversations; if it is an SMS channel, it includes all endpoints related to SMS

Additionally, there are other scope types that vary depending on the channel, product, and different use cases. You can review all available scopes on the Create API key (opens in a new tab) page.

API scope configuration

To configure API scope(s), you will need to allow the API key to access each API endpoint you want to use. To do that, first check the documentation of the API endpoint. It will list the required scopes. Granting any of them will enable the API key to access the endpoint.

You can grant new scopes to an existing API key by editing it or create a new one with scopes from the beginning.

You can manage API keys either through dedicated API (opens in a new tab), or through the web interface.

If you want to configure the API scope(s) through the web interface, navigate to Developer Tools → API Keys → Create API key (opens in a new tab).

From there, enter the following information for the API key:

• Name
• Creation date
• Expiration date
• Allowed IP addresses (optional)

In the next section, API scopes, choose which scopes you want to include:

• General
• Channels
• Connectivity
• Platform
• Customer Engagement
• Web SDK

Upon selecting a specific scope option, a drop-down menu will appear containing all available scopes. From there, you are required to choose which scopes you want to include in the API key.

Available API scopes

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

User roles and API scopes

If you cannot use the API key and must rely on basic authentication, you need to ensure that the user whose password you are using to call API endpoints has been granted the necessary scope to access those endpoints. Unlike API keys, scopes are not directly assigned to users. Instead, you can assign roles to the user, and those roles will implicitly grant certain scopes.

Refer to the list below for scopes that are implicitly granted by specific roles:

Errors

You will receive the 403 Forbidden HTTP status code in the response in case provided user or API key is lacking the required scopes:

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

Library exceptions

When using one of the libraries (opens in a new tab), make sure to handle API exceptions.

 
    try {
        SmsResponse smsResponse = sendSmsApi.sendSmsMessage(smsMessageRequest);
    } catch (ApiException apiException) {
        apiException.getCode();
        apiException.getResponseHeaders();
        apiException.getResponseBody();
    }
 

 
    try
    {
        var result = api.SendSmsMessage(smsRequest);
    }
    catch(ApiException apiException)
    {
        var errorCode = apiException.ErrorCode;
        var errorContent = apiException.ErrorContent;
    }