How to authenticate with a Vonage Contact Center (VCC) API
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.
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) |
|---|---|---|
View agent availability | agents-availability:read | |
Read VCC user details, settings, and presences | users:read | |
Update VCC user details, settings, and presences | users:write | |
Read or download interaction content | interaction-content:read | |
View Insights stats | stats | |
Delete interaction content (e.g. call recordings, transcripts) | interaction-content:delete | |
Read or download interaction content Includes scheduling an export of interaction content from Vonage Contact Center to an external storage provider | interaction-content:read | |
Create and update active interactions | interactions:write | |
Create secure payment sessions | globalpci | |
Read VCC user details, settings, and presences | users:read | |
Update VCC user details, settings, and presences | users:write | |
Read VCC administration settings | admin:read | |
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. |
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.
4. Click OK. Your new credentials appear—without the secret—in API Credentials.
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.