Retrieve a User Code and Verification URL
To retrieve a user code and verification URL, your device must make a POST request to Login with Amazon. If the Device Authorization Request is valid, you will receive a Device Authorization Response that contains the user_code and verification_url you will display to your user.
The Device Authorization Response and request implement sections 3.1 and 3.2 of the OAuth 2.0 Device Flow Specification.
Device Authorization Request
To request authorization, the device must make a secure HTTP POST request to https://api.amazon.com/auth/o2/create/codepair with the following parameters:
Parameter | Description |
---|---|
response_type | REQUIRED. The type of response requested. Must be device_code to proceed with a code-based linking authorization request. |
client_id | REQUIRED. The client identifier. This value is obtained using the Login with Amazon SDK for Android or iOS. |
scope | REQUIRED. The scope of the request. Must be profile, profile:user_id, postal_code, or some combination, separated by spaces (for example, profile%20postal_code). |
For example:
POST /auth/o2/create/codepair HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded
response_type=device_code&client_id=amzn1.application-oa2-client.5e0256cabe&scope=profile
Device Authorization Response
If the Device Authorization Request was properly formatted, you will receive a Device Authorization Response from Login with Amazon that contains the following parameters:
Parameter | Description |
---|---|
user_code | String. The code to display to the user. |
device_code | String. Required to submit a Device Token Request to Login with Amazon, to obtain the user’s access and refresh token. |
verification_uri | String. The URL to display to the user. |
expires_in | Integer. The length of time in seconds the device_code is valid. |
interval | Integer. The length of time in seconds you should wait between each Device Token Request. |
For example:
HTTP/1.1 200 OK
Content-Type: application/json
{
"device_code": "74tq5miHKB",
"user_code": "94238",
"verification_uri": "http://www.example.com/device",
"expires_in": 600,
"interval": 30
}
Authorization Errors
If the authorization request is malformed or an error occurs, the Device Authorization response will return one of the following:
Error Code | Description |
---|---|
invalid_request |
The request is missing a required parameter, has an invalid value, or is otherwise improperly formed. |
unauthorized_client |
The client is not authorized to request an authorization code. |
access_denied |
The resource owner or authorization server denied this request. |
unsupported_response_type |
The request specified an unsupported response type. For this scenario, the response_type must be code . |
invalid_scope |
The client requested the wrong scope. |
server_error |
The authorization server encountered an unexpected error (treat as a 500 Internal Server HTTP error). |
temporarily_unavailable |
The authorization server is currently unavailable due to a temporary overload or scheduled maintenance (treat as a 503 Service Unavailable HTTP error). |