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.
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==
client_id and client_secret are required if the basic authorization header is not used. |
grant_type
Type | Required | Example |
---|---|---|
String | True | client_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
Type | Required | Example |
---|---|---|
String | False | lmccg0ujju2 |
The account key identifier.
client_secret
Type | Required | Example |
---|---|---|
String | False | KnS5GfKULFLp2oTouY0Y2MLEWQi4wERm451sYBTQ= |
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.
Secrets generated can contain non alphanumeric characters that, when included in a URL encoded body, will be misinterpreted. |
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: |
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==" |
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}" |
Returns a HTTP response code of 200.
{ "access_token": "a1b2c3d4e5f6g7h8i9j0", "token_type": "bearer", "expires_in": 300 } |
Returns an HTTP response code of 400.
{ "error": "invalid_request" } |
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." } |