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. 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
| 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
{
"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.