Introduction

HTTP requests to the REST API are protected with a Bearer Token (OAuth). In summary, you will utilize your Sangoma Basic token to obtain an Access Token for using our APIs. The Access Token has a one-year expiration.

Requesting a Basic Token

Go to System > Configuration > CPaaS Credentials

Click in the ADD CREDENTIALS button

On the followin modal window click the SAVE button

You should receive your new Client ID and Client Secret

This info is needed for the next request in order to receive a OAuth token.

The CPaaS Credentials settings will only be accessible and fully functional if your tenant has been properly setup with a CPaaS Account UUID. For existing production customers, this tenant information should be automatically backfilled by CX, so they usually won’t need to worry about this requirement. If you’re executing this feature on QA and staging environments, you might need to manually populate this tenant field on the tenant administration / root tenant.

If you get an error generating the Basic Token, please contact Sangoma Support to get assistance.

Requesting Access Token

To obtain an Access Token, use the /oauth/token endpoint and include your Basic Token in the Authorization header.

curl --location 'https://auth.sangoma.com/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--basic --user <client_id>:<client_secret> \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=<api scopes separated by blank spaces>'

Replace <client_secret> with the provided basic token Client Secret.

If you request scope=cx.agent-calls cx.queue-calls as your API scopes, the result of this request should result on a similar payload as:

{
    "access_token": "YOUR_ACCESS_TOKEN",
    "scope": "cx.agent-calls cx.queue-calls",
    "token_type": "bearer",
    "expires_in": 24304413
}

The access_token field value is what you should use in the Authorization header for subsequent requests. expires_in details when the token will exprie in seconds. Token can be renewed only once it is expired.

You should always request for at least one API scope. You can ask for how many scopes you want, as long as their identifiers are separated by a blank space as in the example above.

An OAuth token will only grant you access to API endpoints covered by the scopes you’ve asked. You can generate as many OAuth tokens as you wish, so if you have multiple applications, you’re encouraged to generate different OAuth tokens using your Basic credentials to shrink possible attack surfaces.

Sangoma CX

API Authentication

Introduction

Requesting a Basic Token

Requesting Access Token

Return to Documentation Home I Return to Sangoma Support