Access Token Retrieval REST API Reference

Use the Access Token Retrieval REST API to request credentials to access Alexa. You can request access outside of a skill session from your app or service, or you can request access on behalf of a customer. The API retrieves the access token from the Login with Amazon (LWA) OAuth 2.0 server.

API endpoint

The LWA endpoint is https://api.amazon.com/auth/o2/token.

Authentication

To retrieve an access token, 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 or by using the Alexa Skills Kit (ASK) Command Line Interface (CLI) get-skill-credentials command.

Operations

The Access Token Retrieval API includes the following operations.

Operation HTTP method and URI

Get access token with authorization code

POST /auth/o2/token HTTP/1.1

Get access token with skill credentials

POST /auth/o2/token HTTP/1.1

Refresh access token

POST /auth/o2/token HTTP/1.1

Get access token with authorization code

Generate an access token on behalf of the customer. You include your skill credentials and an authorization code that identifies the customer. Use the access token in subsequent requests to Alexa.

For more details, see Access Token Request to LWA.

Request

To generate a token, you make a POST request to the /auth/o2/token resource.

Request path and header 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

Request path and header parameters

The request path and header have no parameters.

Request body example

Copied to clipboard.

grant_type: authorization.code.1
&code: customer.auth.code.1
&client_id: your.client.id
&client_secret: your.client.secret

Request body properties

Property Description Type Required

grant_type

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

String

Yes

code

Authorization code that identifies the customer.
Valid value: 18–128 characters.

String

Yes

client_id

Unique identifier for the skill.

String

Yes

client_secret

Unique token for the skill, known only to Alexa and the OAuth 2.0 server.

String

Yes

redirect_uri

Address to where the authorization service should redirect the user. Required if you provided a redirect_uri for the LWA authorization request.

String

No

Response

A successful response returns HTTP 200 OK, along with access and refresh bearer tokens. On error, the response returns the appropriate HTTP status code, error code, and error description.

When you send requests to the Alexa, set the token type to bearer in the REST API Authorization header and the endpoint.scope object in smart home APIs. When the access token expires, obtain a new token by following the procedure in Refresh access token, and then use the new access token in your requests. After your token expires, the response returns HTTP 403 Forbidden with a message that says "Request is not authorized."

Response example

The following example shows a response with a JSON response body.

HTTP/1.1 200 OK
 Content-Type: application/json;charset UTF-8
 Cache-Control: no-store
 Pragma: no-cache
 {
    "access_token":"some.accesstoken.1",
    "token_type":"bearer",
    "expires_in":3600,
    "refresh_token":"some.refreshtoken.1"
 }

Response body properties

Property Description Type

access_token

Access token for the customer account.
Maximum size: 2048 bytes.

String

token_type

Type of token. Always set to bearer.

String

expires_in

Number of seconds before the access token becomes invalid.

Integer

refresh_token

Refresh token for the customer account. Allows your skill to request a new access token from LWA.
Maximum size: 2048 bytes.

String

HTTP status codes

Status Description

200 OK

Response body contains the access and refresh tokens.

400 Bad request

Indicates one of the following errors:

  • 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.

For details about why the request failed, check the error.error_description parameter of the JSON response and the OAuth 2.0 specification description for that error.

401 Unauthorized

Client credential authentication failed.

403 Forbidden

Access or refresh token expired, revoked, or is invalid.

500 Server Error

Error occurred on the server. You 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.

Sample cURL request

curl -k -X POST -H
 'Content-Type: application/x-www-form-urlencoded' -d
'grant_type=authorization_code&client_id=your.client.id&client_secret=your.client.secret&code=authorization.code.1'
 https://api.amazon.com/auth/o2/token

Get access token with skill credentials

Generate an access token to authenticate your app or service with Alexa. You include your skill credentials and the scope or operations that you want to use. You can use the access token in requests to the Alexa REST APIs outside of a skill session, such as in your app or skill management tools.

You can also generate access tokens by using the Alexa Skills Kit (ASK) Command Line Interface (CLI) generate-lwa-tokens command.

Request

To generate a token, you make a POST request to the /auth/o2/token resource.

Request path and header 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

Request path and header parameters

The request path and header have no parameters.

Request body example

Copied to clipboard.

grant_type: client_credentials
&client_id: your.client.id
&client_secret: your.client.secret
&scope=alexa.api.scope

Request body properties

Property Description Type Required

grant_type

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

String

Yes

client_id

Unique identifier for the skill.

String

Yes

client_secret

Unique token known only to Alexa and the OAuth 2.0 server.

String

Yes

scope

Requested scope of access.
You set this parameter to the operations that you need for your skill. For REST API scopes, see Operation scopes or the documentation for the feature that you're implementing in your skill.
If you include more than one scope, separate with "+".

String

Yes

Response

A successful response returns HTTP 200 OK, along with a bearer token. On error, the response returns the appropriate HTTP status code, error code, and error description.

When you send requests to the Alexa, set the token type to bearer in the REST API Authorization header and the endpoint.scope object in smart home APIs. When the access token expires, obtain a new token by following the procedure in Refresh access token, and then use the new access token in your requests. After your token expires, the response returns HTTP 403 Forbidden with a message that says "Request is not authorized."

Response example

The following example shows a response with a JSON response body.

HTTP/1.1 200 OK
 Content-Type: application/json;charset UTF-8
 Cache-Control: no-store
 Pragma: no-cache
 {
    "access_token":"some.accesstoken.1",
    "token_type":"bearer",
    "expires_in":3600,
    "scope": "alexa.api.scope"
 }

Response body properties

Property Description Type

access_token

Token for the skill.
Maximum size: 2048 bytes.

String

token_type

Type of token. Always set to bearer.

String

expires_in

Number of seconds before the access token becomes invalid.

Integer

scope

Granted scope of access.

String

HTTP status codes

Status Description

200 OK

Response body contains the access token.

400 Bad request

Indicates one of the following errors:

  • 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.

For details about why the request failed, check the error.error_description parameter of the JSON response and the OAuth 2.0 specification description for that error.

401 Unauthorized

Client credential authentication failed.

403 Forbidden

Access or refresh token expired, revoked, or is invalid.

500 Server Error

Error occurred on the server. You 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.

Sample cURL request

curl -k -X POST -H
 'Content-Type: application/x-www-form-urlencoded' -d
'grant_type=client_credentials&client_id=your.client.id&client_secret=your.client.secret&scope=alexa.api.scope'
 https://api.amazon.com/auth/o2/token

Refresh access token

Get a new access token from the refresh token. You include your skill credentials and the previous access code. Use the new access token in subsequent requests to Alexa.

For more details, see Using Refresh Tokens with LWA.

Request

To generate a token, you make a POST request to the /auth/o2/token resource.

Request path and header 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

Request path and header parameters

The request path and header have no parameters.

Request body example

Copied to clipboard.

grant_type: refresh_token
&refresh_token: some.refreshtoken.1
&client_id: your.client.id
&client_secret: your.client.secret

Request body properties

Property Description Type Required

grant_type

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

String

Yes

refresh_token

Refresh token from a previous Get access token with authorization code or Refresh access token request.

String

Yes

client_id

Unique identifier for the skill.

String

Yes

client_secret

Unique token for the skill, known only to Alexa and the OAuth 2.0 server.

String

Yes

Response

A successful response returns HTTP 200 OK, along with the bearer access token, the refresh token, and the number of seconds before the access token becomes invalid. On error, the response returns the appropriate HTTP status code, error code, and error description.

When you send requests to Alexa, set the token type to bearer in the REST API Authorization header and the smart home API[endpoint.scope] object. When the access token expires, obtain a new token by following the procedure in Refresh access token and use the new access token in your requests. After your token expires, the response returns HTTP 403 Forbidden with a message that says "Request is not authorized."

Response example

The following example shows a response with a JSON response body.

HTTP/1.1 200 OK
 Content-Type: application/json;charset UTF-8
 Cache-Control: no-store
 Pragma: no-cache
 {
    "access_token":"some.accesstoken.1",
    "token_type":"bearer",
    "expires_in":3600,
    "refresh_token":"some.refreshtoken.1"
 }

Response body properties

Property Description Type

access_token

New access token for the customer account.
Maximum size: 2048 bytes.

String

token_type

Type of token. Always set to bearer.

String

expires_in

Number of seconds before the access token becomes invalid.

Integer

refresh_token

Refresh token for the customer account. Allows your skill to request a new access token from LWA.
Maximum size: 2048 bytes.

String

HTTP status codes

Status Description

200 OK

Response body contains the access and refresh tokens.

400 Bad request

Indicates one of the following errors:

  • 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.

For details about why the request failed, check the error.error_description parameter of the JSON response and the OAuth 2.0 specification description for that error.

401 Unauthorized

Client credential authentication failed.

403 Forbidden

Access or refresh token expired, revoked, or is invalid.

500 Server Error

Error occurred on the server. You 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.

Sample cURL request

curl -k -X POST -H
 'Content-Type: application/x-www-form-urlencoded' -d
'grant_type=refresh_token&client_id=your.client.id&client_secret=your.client.secret&code=authorization.code.1'
 https://api.amazon.com/auth/o2/token
Was this page helpful?

Last updated: frontmatter-missing