Retrieve an Access Token and Refresh Token

LWA for TVs and Other Devices

STEP 1:
Register your App

→

STEP 2:
Retrieve a User Code and Verification URL

→

STEP 3:
Display the User Code and Verification URL

→

STEP 4:
Retrieve an Access Token and Refresh Token

→

STEP 5:
Obtain Customer Profile Information

→

STEP 6:
Log out Users

→

STEP 7:
Integrate with Your Account System

As soon as the Device Authorization Request returns a response, you should begin making Device Token Requests to the token endpoint https://api.amazon.com/auth/o2/token for the user’s access token.

You must poll the endpoint at an interval which does not exceed the interval value in the Device Authorization Response. Poll the endpoint until you receive an access token, until the request is denied by the user, or until the device_code expires (the value of the expires_in parameter of the Device Authorization Response).

Until the user has entered their code, the Device Token Response will only return authorization_pending. After the user has successfully entered their code, the Device Token Response will include their access and refresh token.

Device Token Request
Device Token Response
Device Token Errors
Using Refresh Tokens

Device Token Request

To request the user’s access token from Login with Amazon, make a secure HTTP POST request to https://api.amazon.com/auth/o2/token with the following parameters:

Parameter	Description
`grant_type`	REQUIRED. Must be device_code to proceed with this scenario.
`device_code`	REQUIRED. The device_code value returned in the Device Authorization Response from Login with Amazon.
`user_code`	REQUIRED. The `user_code` value returned in the Device Authorization Response from Login with Amazon.

For example:

POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded

user_code=AAYJHL&device_code=B66fd882-7405-4e9a-bfb9&grant_type=device_code

The Device Token Request implements section 3.4 of the OAuth 2.0 Device Flow specification.

Device Token Response

After the user has completed entering their code, the Device Token Response you receive from Login with Amazon will contain the following parameters:

Parameter	Description
`access_token`	String. The access token for the user. Maximum size of 2048 bytes.
`refresh_token`	String. The refresh token that can be used to request a new access token. Maximum size of 2048 bytes.
`token_type`	String. Will always be bearer.
`expires_in`	Integer. The number of seconds the access token is valid.

For example:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "2YomnFZEjfjklsadjkwpAA",
    "token_type": "bearer",
    "expires_in": 3600,
    "refresh_token": "nGzv3JORFQXG3x21KW1a"
}

The Device Token Response implements section 3.5 of the OAuth 2.0 Device Flow specification

Device Token Errors

The Device Token Response can return errors if the request is malformed or there is an issues with the server:

</colgroup>

Error Code	Description
`invalid_request`	The request is missing a required parameter, has an invalid value, or is otherwise improperly formed.
`invalid_client`	The client authentication failed. This is used in cases where the authorization service does not return an HTTP 401 (Unauthorized) status code.
`invalid_grant`	The authorization grant or refresh token is invalid, expired, revoked, does not match the Device Token Request, or was issued to another client.
`unauthorized_client`	The authenticated client is not authorized to perform a Device Token Request.
`unsupported_grant_type`	The wrong token_type was indicated. Must be bearer.

The Device Token Response may also include errors which are specific to this type of token request:

Error Code	Description
`authorization_pending`	The user has not yet entered their user code at the verification URL.
`slow_down`	The device is polling too quickly. Make Device Token Requests only as frequently as indicated by the interval in the Device Authorization Response.
`expired_token`	The device_code has expired. You will need to make a new Device Authorization Request.

If you're troubleshooting the error {"error_description":"The request is missing a required parameter : client_secret","error":"invalid_request"}, note that the documentation here assumes that you obtained the client_id by creating a setting in Device Settings. This process doesn't issue a client_secret at all. See Using Refresh Tokens for information about getting an LwA refresh token.

Using Refresh Tokens

Access tokens will expire after a set time period (normally returned in the expires_in parameter). When you obtain an access token, you will also receive a refresh token. You can use a refresh token to retrieve a new access token.

To submit a refresh token, the client makes a secure HTTP POST to https://api.amazon.com/auth/o2/token with the following parameters:

Parameter	Description
`grant_type`	REQUIRED. The type of access grant requested. Must be `refresh_token`.
`refresh_token`	REQUIRED. The refresh token returned by the original Access Token Response.
`client_id`	REQUIRED. The client identifier. This should match the `client_id` you included in your Device Authorization Request.

For example:

POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8

grant_type=refresh_token&refresh_token=Atzr|IQEBLzAtAhRPpMJxdwVz2Nn6f2y-tpJX2DeX...&client_id=foodev

Tip: Refresh tokens contain characters that are outside the allowed range for URLs. Therefore, you should URL encode access tokens to prevent errors. For more information, see Section 2.1 of RFC3986.

The response to a refresh token submission is a Device Token Response.