Responses (Authentication API)

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

HTTP headers include:

HTTP/1.1 CODE MESSAGE
Content-Type: application/json; charset=utf-8
Content-Length: 7

The response body contains either the requested information or an error message:

{
    "message":"MESSAGE"
}

Successful response

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 Vonage Contact Center API you specify in the scope request body parameter.

The token is returned in JSON format:

{
  "token_type": "bearer",
  "access_token": "e33f83202b474c52b5f059b19cah9",
  "expires_in": 7200
}

Your bearer access token is only valid for use for two hours after being issued (as specified in the expires_in item which is expressed in seconds). After this time, the token expires and you must request a new token.

Unsuccessful response and error codes

Errors return an error status code, such as 400 Bad Request. Additional information is included in the body of the return call in JSON format, usually in the following format:

{
  "error": "Internal Server Error",
  "error_description": "An internal server error occurred"
}

Error code 400 Bad Request

The request returns 400 Bad Request in response to various invalid requests:

Invalid grant_type

If you do not provide a value for the grant_type parameter, or provide an invalid value, you receive the following message in addition to the 400 error code:

{
  "error": "unsupported_grant_type",
  "error_description": "Invalid grant_type"
}

Set the grant_type request body parameter to ‘client_credentials’.

Invalid scope

If you do not provide a value for the scope parameter, or provide an invalid value, you receive the following message in addition to the 400 error code:

{
  "error": "invalid_scope",
  "error_description": "You must specify a scope"
}

or

{
  "error": "invalid_scope",
  "error_description": "\"vonage/api/stats\" is an invalid scope"
}

Set the scope request body parameter to the root URL of the API you are authenticating with. For example, scope=stats.

Error code 401 Unauthorized

The request returns 401 Unauthorized in response to invalid or missing client credentials.

Invalid client authentication

If you do not provide your client credentials or provide an incorrect value or values in the client_id and client_secret request body parameters, you receive the following message in addition to the 401 error code:

{
  "error": "invalid_client",
  "error_description": "Invalid client authentication"
}

Error code 500 Internal Server Error

An internal server error occurred.

Token expiration

Your bearer access token is only valid for use for two hours after being issued. After this time, the token expires and you receive a 401 Unauthorized error. You must request a new token.