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
  • HTTP Header
    • Parameters of HTTP Header
  • Request Body Syntax
  • Request Body Parameters
  • Sample cURL Request
• Response Format
  • HTTP Header
  • Response Body Syntax
  • Response Parameters
  • Errors

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

Parameter	Description	Example
Content-Type	The 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

Parameter	Description	Example
grant_type	Value must be client_credentials.	grant_type=client_credentials
client_id	The ClientId value from the developer console.	client_id=xxxx
client_secret	The ClientSecret value from the developer console.	client_secret=xxxx
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

Parameter	Description	Example
X-Amzn-RequestId	A 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-Type	The content type of the resource: application/json	Content-Type: application/json

Response Body Syntax

Response Parameters

Parameter	Description	Example
access_token	An access token that must be used for all requests.	"access_token":"Atc|MQEWYJxEnP3I1ND03Zz..."
expires_in	The 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
scope	The scope specified in the access token request. Value will be alexa:skill_messaging.	"scope":"alexa:skill_messaging"
token_type	The 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 Code	Type	Description
400	INVALID_REQUEST	Reasons 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.