Request Access to Send Messages to Your Skill
For out-of-session requests, your app or service must implement an OAuth 2.0 exchange with the Login with Amazon (LWA) OAuth server for each customer that enables your skill. This exchange gives your app access to your skill on behalf of the customer. Later, you provide the customer access token in the Skill Messaging REST API to send a message to your skill.
Follow these guidelines to obtain and manage access tokens.
You can also obtain these credentials via SMAPI with the Skill Credentials API.
LWA endpoint
The LWA endpoint is https://api.amazon.com/auth/o2/token
.
Request access tokens from LWA
To start the access token flow with LWA, you need your skill credentials. You can obtain your client ID and client secret for your skill from the Permissions menu in the Alexa developer console.
Request example
POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
grant_type: client_credentials
&client_id: your.client.id
&client_secret: your.client.secret
&scope=alexa:skill_messaging
Request body
Parameter | Description | Type | Required |
---|---|---|---|
|
Type of access grant requested. You must set this parameter to |
String |
Yes |
|
Client identifier for your skill from the Permissions menu in the Alexa developer console. |
String |
Yes |
|
Client secret for your skill from the Permissions menu in the developer console. |
String |
Yes |
|
Requested scope of access. You must set this parameter to |
String |
Yes |
redirect_uri
in your request.Response
On success, the HTTP response includes the bearer access token, the refresh token, and the number of seconds before the access token becomes invalid. Store these tokens with the grantee access token so that you can always associate the tokens with the customer.
Response example
HTTP/1.1 200 OK
Content-Type: application/json;charset UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"someAccessToken",
"token_type":"bearer",
"expires_in":3600,
"scope":"alexa:skill_messaging",
"refresh_token":"someRefreshToken"
}
Response body
The response body includes the following parameters. LWA encodes these parameters with the application/json
media type.
Parameter | Description | Type | Required |
---|---|---|---|
|
Token for the customer account. |
String |
Yes |
|
Type of token. Always set to |
String |
Yes |
|
Number of seconds before the access token becomes invalid. |
Integer |
Yes |
|
Granted scope of access. You must set this parameter to |
String |
Yes |
|
Token that allows your skill to request a new access token from LWA. |
String |
Yes |
This section documents the format for the POST request to obtain an access token.
HTTP status codes
If your request isn't successful, you receive a non-200 HTTP status code. The response body might include the reason
parameter.
Status | Description |
---|---|
|
Indicates that one or more properties in the header or request body are invalid, missing, or malformed. |
|
Client isn't authorized to perform the requested operation. |
|
Grant type isn't supported by the authorization server. |
|
Requested scope isn't valid. |
|
Client credential authentication failed. |
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Related topics
- Access the Alexa Shopping and To-Do Lists
- LWA Access Token Request
- Skill Events in Alexa Skills
- Skill Messaging API Reference
Last updated: Sep 21, 2023