Authorize an AVS Device Through Code-Based Linking (CBL)

The instructions on this page describe how to implement code-based linking (CBL), an authorization method optimal for products with limited or no access to character input, such as a television or smart watch.

During product registration, send the user a short alphanumeric code and a URL. On a separate device with access to a browser, the user visits the URL, logs in with their Amazon credentials, and enters the short code to link the product with their Amazon account. After linked their account, the product notifies the user with a splash screen and provides access to AVS.

Process overview for implementing CBL

To implement CBL

Obtain your client ID and client secret and record this value..
Post a device Authorization Request
Direct the user to log in
Request device tokens
Exchange the refresh token for a new access token

The following diagram illustrates the exchanges between your AVS-enabled product and LWA to obtain an access_token and refresh_token for use with AVS:

Code-Based Linking Sequence Diagram — Click to enlarge

Step 1: Locate your client ID

To locate your client ID

With your Amazon developer credentials log in to the developer console, select Alexa Voice Service, then either enable CBL for an existing product or create a new product:
- Click Manage to enable CBL for an existing product.
- Click Create Product to create a new product.
Click the Security Profiles tab, then select Other devices and platforms.
Enter a Client ID name, then click Generate ID.
Save the Client ID somewhere for later use.

Step 2: Post a device Authorization Request

Your AVS-enabled device must make a POST request to obtain the appropriate user code and URL from LWA. If the device receives valid response, display the user_code and verification_uri to the user.

Note: This API implements the Device Authorization Request component of the OAuth code-based linking specification.

Use the following endpoint for your request: https://api.amazon.com/auth/O2/create/codepair

The request must include the following parameters:

response_type– The expected value is device_code, which specifies a CBL request.
client_id– The Client ID you obtained in Locate your client ID.
scope– The expected value is alexa:all. This specifies permissions for your product.
scope_data– Additional JSON that includes product-specific information, such as productID and deviceSerialNumber.
- productID– The Device Type ID for your product.
- productInstanceAttributes– an object containing the deviceSerialNumber.
  - deviceSerialNumber– A key that uniquely identifies this instance of your product. For example, this could be a serial number or MAC address.

The following example shows a scope object before URL-encoding. Use the following sample requests for reference:

    {
      "alexa:all": {
        "productID": "{{productId}}",
        "productInstanceAttributes": {
            "deviceSerialNumber": "{{deviceSerialNumber}}"
        }
      }
    }

Note: You can include the Accept-Language header in your request to select the language the login and registration language for your user. Accepted values are: en-US, de-DE, es-ES, en-GB, fr-FR, it-IT, pt-BR, ja-JP, zh-CN. .

Sample Request

The following example demonstrates a curl request to obtain an LWA user code and URL:


curl -k -d 'response_type=device_code&client_id={{client_id}}&scope=alexa%3Aall&scope_data=%7B%22alexa%3Aall%22%3A%7B%22productID%22%3A%22Speaker%22,%22productInstanceAttributes%22%3A%7B%22deviceSerialNumber%22%3A%2212345%22%7D%7D%7D' -H "Content-Type: application/x-www-form-urlencoded" -X POST https://api.amazon.com/auth/O2/create/codepair

Sample response

The response follows the format described by the section 3.4 of the OAuth specification. If the input is valid, the response has the following structure:

{
    "user_code": "{{STRING}}",
    "device_code": "{{STRING}}",
    "verification_uri": "{{STRING}}",
    "expires_in": {{INTEGER}},
    "interval": {{INTEGER}}
}

Response parameters

Parameter	Description	Type
user_code	The code displayed to the user. The user enters this code during registration.	string
device_code	Private code returned in the Device Authorization Response from LWA.	string
verification_uri	URL that you present to the user.	string
expires_in	Length of time in seconds that the codes are valid.	integer
interval	Interval in seconds for time between Device Token Requests.	integer

Possible errors

HTTP 400: MissingValue
HTTP 500: ServiceError
HTTP 503: ServiceUnavailable

Step 3: Direct the user to log in

To direct the user to log in

When your device receives a response to the Device Authorization Request, it must display the user_code and verification_uri to the user.

For guidance and examples, see Setup and Authentication.

The user navigates to the verification_uri and are instructed to login with their Amazon credentials and enter the provided user_code. The Code Registration Page implements the User Instruction component of the OAuth specification.

This is a sample registration page.
After entering the user_code, Amazon directs the user to a page indicating a successful or failed authentication. If authentication fails, the page provides the reason for failure, such as code already authorized or unrecognized code.

Step 4: Request device tokens

After instructing the user to log in, the device begins polling for an access_token and refresh_token.

Use the following endpoint for your request: https://api.amazon.com/auth/O2/token

The request must include the following headers:

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

The request must include these parameters:

grant_type: The expected value is device_code. This informs the service of the grant type.
device_code: The code returned in Device Authorization Request.
user_code: The code displayed to the user. The user enters this code during registration.

Sample response

After the user completes the registration flow, the response matches the following structure:

{
  "access_token": "{{STRING}}",
  "refresh_token": "{{STRING}}",
  "token_type": "bearer",
  "expires_in": {{INTEGER}}
}

Response parameters

access_token: The access token.
refresh_token: The refresh token.
token_type: Bearer.
expires_in: The number of seconds the access token is valid.

Note: Because the user could some time to complete registration or could abandon registration, during polling, you could receive the following responses: authorization_pending, slow_down, invalid_code_pair, invalid_client, unauthorized_client. On invalid_code_pair, restart the registration flow.

Step 5: Exchange the refresh token for a new access token

When the access token expires or is about to expire, exchange the refresh token for a new access token. If the token exchange fails, the device should retry the exchange with an exponential back-off. Create a new connection with AVS after receiving and updating the tokens. Make a POST to https://api.amazon.com/auth/O2/token with the following parameters in the constructed URL:

grant_type: refresh_token
refresh_token: Refresh token.
client_id: Client ID.

The response includes the following values:

access_token: Access token.
refresh_token: Refresh token.
token_type: bearer
expires_in: Number of seconds for which the access token is still valid.

Last updated: Mar 31, 2021