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

Copied to clipboard.

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

grant_type

Type of access grant requested. You must set this parameter to client_credentials.

String

Yes

client_id

Client identifier for your skill from the Permissions menu in the Alexa developer console.

String

Yes

client_secret

Client secret for your skill from the Permissions menu in the developer console.

String

Yes

scope

Requested scope of access. You must set this parameter to alexa:skill_messaging.

String

Yes

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

access_token

Token for the customer account.
Maximum size: 2048 bytes.

String

Yes

token_type

Type of token. Always set to bearer.

String

Yes

expires_in

Number of seconds before the access token becomes invalid.

Integer

Yes

scope

Granted scope of access. You must set this parameter to alexa:skill_messaging.

String

Yes

refresh_token

Token that allows your skill to request a new access token from LWA.
Maximum size: 2048 bytes

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

400 INVALID_REQUEST

Indicates that one or more properties in the header or request body are invalid, missing, or malformed.

400 UNAUTHORIZED_CLIENT

Client isn't authorized to perform the requested operation.

400 UNSUPPORTED_GRANT_TYPE

Grant type isn't supported by the authorization server.

400 INVALID_SCOPE

Requested scope isn't valid.

401 INVALID_CLIENT

Client credential authentication failed.

500 SERVER_ERROR

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 SERVICE_UNAVAILABLE

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Last updated: Oct 14, 2022