This guide describes how to get a bearer access token to authenticate your requests through our regional API gateway.

To use any VCC API, you need a bearer access token. Your bearer access token authenticates your request to the API. The API can check that you are authorized to make your specific request.

In this page

Getting a bearer access token

To get a bearer access token, you first need to get API credentials from VCC. Using these API credentials you can then request a bearer access token.

Scopes

Scopes define which API, or APIs, and resources your API credentials can access and what actions you can perform using the API with these credentials. You specify one or more scopes when you create your credentials. When you request a bearer access token for your credentials, you need to specify which one of the scopes the token is for.

The scope for API credentials for most VCC APIs is in the format object:action. For example, agents-availability:read gives read access resources in the Agents Availability API, and interaction-content:read gives read access to interactions returned by the Conversation Analyzer API.

API	Scope description (as in API Credentials)	Scope value (in API requests)
Agent Availability API	View agent availability	agents-availability:read
Agents API	Read VCC user details, settings, and presences	users:read
Agents API	Update VCC user details, settings, and presences	users:write
Conversation Analyzer API	Read or download interaction content	interaction-content:read
Insights Stats API	View Insights stats	stats
Interaction Content API and Interaction Content Export API	Delete interaction content (e.g. call recordings, transcripts)	interaction-content:delete
Interaction Content API and Interaction Content Export API	Read or download interaction content Includes scheduling an export of interaction content from Vonage Contact Center to an external storage provider	interaction-content:read
Interactions API	Create and update active interactions	interactions:write
Payment API	Create secure payment sessions	globalpci
User Admin API	Read VCC user details, settings, and presences	users:read
User Admin API	Update VCC user details, settings, and presences	users:write
Webhooks API	Read VCC administration settings	admin:read
Webhooks API	Update VCC administration settings	admin:write

Getting API credentials from VCC

To make calls to an API, you require API credentials which authenticate your request.

Your API credentials consist of:

your client ID. Your client ID identifies who you are, a bit like a user name.
your client secret. Your client secret is a password that’s generated by VCC.

If you do not already have API credentials, you will need to create them in API Admin. For information about creating new API credentials, see the Creating new API credentials section in this page.

If you already have API credentials and want to reuse these for an additional scope, you can add that scope to your existing credentials. For information about adding a new scope to existing API credentials, see the Adding a scope to your existing API credentials section in this page.

Creating new API credentials

To create API credentials for your account, perform the following steps:

1. Log in to the VCC Admin Portal and go to API Credentials. (If API Credentials does not appear, contact VCC support.)
Click Create New. Create API Credentials appears.

2. Provide the following information:

Field	Description
Name	A name to identify the credentials later. We recommend that you use a name that describes the credential’s intended use. Type a name for the credentials. You can edit this later.
Scopes	The scope or scopes that you want these API credentials to work with. In the Scopes list, click to see the available scopes. Click the name of the scope to add it. Click x alongside the scope name to remove it. Add as many scopes as you like to your API credentials. See the documentation for individual APIs to see which scopes you will require. You can edit the list of scopes later.

Field

Description

Name

A name to identify the credentials later. We recommend that you use a name that describes the credential’s intended use. Type a name for the credentials. You can edit this later.

Scopes

The scope or scopes that you want these API credentials to work with.

In the Scopes list, click to see the available scopes.

Click the name of the scope to add it.

Click x alongside the scope name to remove it.

Add as many scopes as you like to your API credentials. See the documentation for individual APIs to see which scopes you will require.

You can edit the list of scopes later.

Create API Credentials in VCC

3. Click Save API credential. A Success message appears and your new credentials appear.
Copy and save your client ID and secret; you cannot retrieve them later. You will need your client ID and client secret every time you make a call to authenticate with a VCC API.
Saved API Credentials in VCC

4. Click OK. Your new credentials appear—without the secret—in API Credentials.
New API Credentials in VCC

Adding a scope to your existing API credentials

If you already have API credentials for a VCC API, you can add other scopes to these credentials. A new scope might give you access to another API, or give you additional access to an API you can already use. From API Credentials, click to open the API credentials you wish to add a scope to. Add scopes as required.

Requesting your bearer access token

Using a tool for making API requests, send your client ID and secret in the request body to the token endpoint. The URL for the token endpoint is https://***.cc.vonage.com/Auth/connect/token, where *** represents a regional subdomain:

Region	URL subdomain	Base URL
EMEA	emea	https://emea.cc.vonage.com
USA	nam	https://nam.cc.vonage.com
APAC	apac	https://apac.cc.vonage.com

Replace *** with the correct subdomain for your region.

The request body requires the following parameters:

Parameter	Description	Example value
`grant_type`	A grant type of client credentials indicates that you are using OAuth 2.0 for authorization.	`client_credentials`
`client_id`	The client ID provided by VCC. The ID identifies you.	`abcde`
`client_secret`	The client secret provided by VCC. The secret is like a password.	`12345`
`scope`	The value of scope determines the API and endpoints with which the bearer access token can be used. See the documentation for individual APIs and endpoints for information about the scope they require.	`agents-availability:read`

Example request

The following examples specify scope=agents-availability:read; the token returned will be for use with the Agents Availability API. To get a bearer access token for a different API, change the scope accordingly.

cURL

curl -X POST \
  https://emea.cc.vonage.com/Auth/connect/token \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=abcde&client_secret=12345&scope=agents-availability%3Aread'

HTTP

POST /Auth/connect/token HTTP/1.1
Host: emea.cc.vonage.com
Content-Type: application/x-www-form-urlencoded
 
grant_type=client_credentials&client_id=abcde&client_secret=12345&scope=agents-availability%3Aread

Response

All requests to the token endpoint return various standard HTTP headers, including the response status code, and a response body in JSON format.

A successful request returns a HTTP response status code of 200 and a bearer access token. You can use the token to authenticate requests to the VCC API you specify in the scope request body parameter.

Token is returned in JSON format:

{
   "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Inh0QTYyRXpEdW1...",
   "expires_in": 7200,
   "token_type": "Bearer"
}

Using a bearer access token

When you have got your bearer access token, use the token to authenticate every request you make to a VCC API.

Using a tool for making API requests, send your bearer access token in the authorization header in your request. You must provide the Bearer keyword to specify that you are using bearer authentication. The following examples call the Get agents-availability endpoint in the Agents Availability API. The bearer access tokens have been replaced with <access_token>.

The root URL for VCC APIs is https://***.api.cc.vonage.com, where *** represents a regional subdomain. URLs in the example code use in place of the region. To access the API for your region, replace with the correct subdomain for your region.

Region	URL subdomain	Base URL
EMEA	emea	https://emea.api.cc.vonage.com
USA	nam	https://nam.api.cc.vonage.com
APAC	apac	https://apac.api.cc.vonage.com

cURL

curl -X GET \
  'https://emea.api.cc.vonage.com/agents-availability?skillNames=French%2CEnglish' \
  -H 'accept: application/vnd.newvoicemedia.v1+json' \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

HTTP

GET /agents-availability?skillNames=French,English HTTP/1.1
Host: emea.api.cc.vonage.com
Content-Type: application/json
accept: application/vnd.newvoicemedia.v1+json
authorization: Bearer <access_token>

Best practices

The following tips help you get the most out of your bearer access token:

By default, your token expires after 15 minutes. You can reuse your token as many times as you like (within any API limits set on your account) during that time. To reuse your token you can cache it until the expiry date time provided in the token.
To avoid errors being returned by your API request due to an expired token, intercept 401 Unauthorized errors with a The access token is invalid or has expired message that your request receives when you use your cached token. If you receive such a message, request a new token and replace the stored value with the new one.

Try it out

For information, see Trying out Vonage Contact Center APIs.

Browser not supported