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

  1. Obtain your client ID and client secret and record this value..
  2. Post a device Authorization Request
  3. Direct the user to log in
  4. Request device tokens
  5. 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

  1. 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.
  2. Click the Security Profiles tab, then select Other devices and platforms.
  3. Enter a Client ID name, then click Generate ID.
  4. Save the Client ID somewhere for later use.
Generate Client Id

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.

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}}"
        }
      }
    }
    
    

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

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

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

    Registration Page
    This is a sample registration page.
  2. 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.

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.