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.

Note: These requests require the ClientId and ClientSecret values for your skill. To obtain these, go to the list of skills in the developer console. Those skills that have the appropriate permissions will show the link View Skill ID and Client Secret. When you click this link, the Skill ID, Client ID, and Client Secret appear in a popup message. Copy these values for later use.

Request Format to Obtain Access Token
Response Format

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=amzn1.iba-client.b2b360f8a77d457981625636121d6edf`
`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

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

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.