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.

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

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).

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

grant_type

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

The account key identifier.

client_secret

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.

Request Examples

Request token using basic authorization

curl -H "Content-Type: application/x-www-form-urlencoded" -X POST "https://***.cc.vonage.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://***.cc.vonage.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."
}