Your Alexa Dashboards Settings

Configure an Application or Service to Send Messages to Your Skill

The third party application back-end that corresponds to the skill you are building needs authorization to send messages to your skill. You get this authorization by obtaining an access token. To obtain an access token, the developer’s server issues a POST request on an HTTPS connection.

See also: Skill Events in Alexa Skills and Skill Messaging API Reference

Request Format to Obtain Access Token

This section documents the format for the POST request to obtain an access token.

HTTP Header

POST /auth/O2/token HTTP/1.1
Host : api.amazon.com
Content-Type : application/x-www-form-urlencoded;charset=UTF-8

Parameters of HTTP Header

ParameterDescriptionExample
Content-TypeThe content type of the resource. Must be application/x-www-form-urlencoded.Content-Type: application/x-www-form-urlencoded

Request Body Syntax

grant_type=client_credentials&client_id=(clientID)&client_secret=(clientSecret)&scope=alexa:skill_messaging

Request Body Parameters

ParameterDescriptionExample
grant_type Value must be client_credentials. grant_type=client_credentials
client_id The ClientId value from the Amazon Developer Portal. client_id=amzn1.iba-client.b2b360f8a77d457981625636121d6edf
client_secret The ClientSecret value from the Amazon Developer Portal. client_secret=c559965801308f2bb79ca787b1dfc8deece8a2fd7d7618946cec1635d26dcbfb
scope Value must be alexa:skill_messaging scope=alexa:skill_messaging

Sample cURL Request

curl -k -X POST -H

'Content-Type: application/x-www-form-urlencoded' -d

'grant_type=client_credentials&client_id=xxxx&client_secret=yyyy&scope=alexa:skill_messaging'

https://api.amazon.com/auth/O2/token

Response Format

This section documents the format of the response to the POST request seeking an access token.

HTTP Header

X-Amzn-RequestId: d917ceac-2245-11e2-a270-0bc161cb589d

Content-Type: application/json
ParameterDescriptionExample
X-Amzn-RequestIdA value created by the server that uniquely identifies the request. If you have problems, Amazon can use this value to troubleshoot. X-Amzn-RequestId: d917ceac-2245-11e2-a270-0bc161cb589d
Content-TypeThe content type of the resource: application/jsonContent-Type: application/json

Response Body Syntax

{
    "access_token":"Atc|MQEWYJxEnP3I1ND03ZzbY_NxQkA7Kn7Aioev_OfMRcyVQ4NxGzJMEaKJ8f0lSOiV-yW270o6fnkI",
    "expires_in":3600,
    "scope":"alexa:skill_messaging",
    "token_type":"Bearer"
}

Response Parameters

ParameterDescriptionExample
access_tokenAn access token that must be used for all requests."access_token":"Atc|MQEWYJxEnP3I1ND03Zz..."
expires_inThe duration in seconds of the access token lifetime. For example, 3600 denotes that the access token expires in one hour from the time the response was generated."expires_in":3600
scopeThe scope specified in the access token request. Value will be alexa:skill_messaging."scope":"alexa:skill_messaging"
token_typeThe type of the token issued. Only Bearer tokens are supported."token_type":"Bearer"

If your request is not successful, you will receive a non-200 error status code. In the case of a non-200 code, the response message may contain the following parameter in the body of the JSONObject:

  • reason: « The reason the request was not accepted. »

Errors

Status CodeTypeDescription
400INVALID_REQUESTReasons for this response include:
- The content type is not supported by the authorization server. In other words, it is not application/x-www-form-urlencoded.
- The request is missing a required parameter: grant-type, scope, client_id, client_secret.
- The request is otherwise malformed.
400 UNAUTHORIZED_CLIENT The client is not authorized for the requested operation.
400 UNSUPPORTED_GRANT_TYPE The grant type is not supported by the authorization server. In other words, it is not client_credentials.
400 INVALID_SCOPE The requested scope is invalid, which means it is not alexa:skill_messaging.
401 INVALID_CLIENT The client authentication failed.
500 SERVER_ERROR There was an internal server error. The requester may retry the request.
503 SERVICE_UNAVAILABLE The server is temporarily unavailable. The requester must retry later honoring the Retry-After header included in the response. See the HTTP/1.1 specification, section 14.37, for possible formats for the Retry-After value.

After obtaining the token, your application can call the Skill Messaging API to send a message to your skill.