Retrieve a User Code and Verification URL

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

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.

Tip: We recommend adding Login with Amazon buttons to your device, and performing the Device Authorization Request when a user selects the button. You can find various Login with Amazon button styles available here. If a button is not optimal for your device (for example, due to a small screen size), you can perform the request when a user selects a particular menu option or hyperlink.

The Device Authorization Response and request implement sections 3.1 and 3.2 of the OAuth 2.0 Device Flow Specification.

Device Authorization Request
Device Authorization Response
Authorization Errors

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