Getting a bearer access token

The POST v{#}/oauth2/token allows you to retrieve a token to access other V0 APIs.

To use the Web API, you must firstly request a bearer access token from the Web API. You can then use this token within the Authorization header when calling other API calls to authorize the request.

Before you can get your bearer access token, you must obtain your account key and API authentication token. For information about getting your account key and API authentication token, see Getting your account key and API authentication token. You then use your account key and API authentication token in the following method, either in the HTTP header Authorization or in the body of the posted form.

We recommend that you send encoded account key and API authentication token values in the Authorization header and post only the grant_type parameter in the body of the request.

The token that the following method returns is only valid for use for one hour after being issued. After this time, the token expires and you must request a new access token.

In this page

Header Parameters

The endpoints requires the following headers:

Content-Type(required)

application/x-www-form-urlencoded

Indicates the content type required from the server is in standard URL encoded format.

Authorization(required)

Basic Client_Id:Client_Key

Authorization is only required if client_id and client_secret are not provided as form parameters.

Client_Id:Client_Key is a string consisting of the client_id (your account key) separated by a colon then your client_secret (your API authentication token).

This entire Client_Id:Client_Key sequence is then Base64 encoded before being passed to the token issuer.

For example, the following string represents an account with the account key "a1b2c3d4e5" and the API authentication token "9pBl+xY1MW+AbsdZk4xpv7NwWxG8+oqduKiSqVybM9Y=":

a1b2c3d4e5:9pBl+xY1MW+AbsdZk4xpv7NwWxG8+oqduKiSqVybM9Y=

Note the colon delimiter.

This string is then Base64 encoded:

YTFiMmMzZDRlNTo5cEJsK3hZMU1XK0Fic2RaazR4cHY3TndXeEc4K29xZHVLaVNxVnliTTlZPQ==

The encoded value is then appended to the Basic keyword passed in the Authorization header:

Authorization: Basic YTFiMmMzZDRlNTo5cEJsK3hZMU1XK0Fic2RaazR4cHY3TndXeEc4K29xZHVLaVNxVnliTTlZPQ==

Request Body Parameters

client_id and client_secret are required if the basic authorization header is not used.

grant_type

TypeRequiredExample
StringTrueclient_credentials

The value of grant_type is always 'client_credentials' indicating that this request for authorization is being made using the OAuth2 client credential grant type. For more information on client-credentials grant type, see http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-4.4.

client_id

TypeRequiredExample
StringFalselmccg0ujju2

The account key identifier.

client_secret

TypeRequiredExample
StringFalseKnS5GfKULFLp2oTouY0Y2MLEWQi4wERm451sYBTQ=

Alphanumeric string that contains the private API authentication token issued to you.

Please note that parameters must be form URL encoded when in the body of the request.

Form Url Encode Your Client ID and Secret

Secrets generated can contain non alphanumeric characters that, when included in a URL encoded body, will be misinterpreted.

For example, an account with the client secret "6lBJodbA0+cAywhyLvhOBo4QfTFO5t6/2B/QetQgw5Y=" contains illegal characters ('+' and '/') and so must be URL encoded to provide something like "6lBJodbA0%2BcAywhyLvhOBo4QfTFO5t6%2F2B%2FQetQgw5Y%3D".

Request Examples


The examples use *** as a placeholder for the regional subdomain. To access the API for your region, replace *** with the correct subdomain for your region:

Request token using basic authorization

curl -H "Content-Type: application/x-www-form-urlencoded" -X POST "https://***.newvoicemedia.com/v0/oauth2/token" -d "grant_type=client_credentials" -H "Authorization: Basic dXNlcjpwYXNzd29yZA=="

Request token using request body

curl -H "Content-Type: application/x-www-form-urlencoded" -X POST "https://***.newvoicemedia.com/v0/oauth2/token" -d "grant_type=client_credentials&client_id={accountKey}&client_secret={secret}"

Response Examples

Example: Successful Response

Returns a HTTP response code of 200.

{
 "access_token": "a1b2c3d4e5f6g7h8i9j0",
 "token_type": "bearer",
 "expires_in": 300
}

Example: Invalid Request

Returns an HTTP response code of 400.

{
 "error": "invalid_request"
}

Example: Invalid Credentials

Returns an HTTP response code of 401, because one or more of the client_id, client_secret, or their Base64 encoded representations are incorrect.

{
 "error": "invalid_client",
 "error_description": "The client secret was incorrect."
}