Retrieve an Access Token and Refresh Token
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
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:
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
The response to a refresh token submission is a Device Token Response.