Authorize an AVS Device Through a Web Service

To access the Alexa Voice Service (AVS), your Alexa Built-in device must obtain a Login with Amazon (LWA) access token. The device includes this token with each request to AVS to authorize the Amazon account for the device user. One way to accomplish this authorization is through a web service. The web service obtains and transfers the authorization code to the device. The device uses this authorization code to obtain access and refresh tokens from LWA, which make the calls to AVS.

The following instructions describes how to implement Alexa Voice Service (AVS) authorization through a web service.

Obtain an access token through a web service on a companion website

The following process describes to obtain an access token through a web service on a companion website:

Click to enlarge

To obtain refresh and access tokens

  1. Register the following information with the web service on your companion website requests the following values from your AVS-enabled device:
    • Product ID
    • Device Serial Number (DSN)

  2. The user navigates to your website and clicks a Login button, which redirects them to the LWA site. For details about constructing the redirect URL, see Create a Login with Amazon Consent Request.

  3. LWA prompts the user to enter their Amazon credentials and to grant access for the device to communicate with AVS on their behalf. For more details about receiving the response from LWA, see Receive the LWA response with the authorization code.
  4. Your web service sends an Authorization Code, client ID, and client secret to LWA.

  5. LWA sends access and refresh tokens to your web service.

    Your web service exchanges the refresh token, client ID, and client secret for a new access token every hour or when the existing token is about to expire. If the token exchange fails, your device should retry the exchange with an exponential back-off. For more details about exchanging tokens, see Exchange the refresh token for a new access token.

  6. Securely transfer the access token from your web service to the device. Create a new connection to AVS after receiving and updating the new tokens.

Implement an LWA consent request

Users create a consent request when they click the Login button on your companion site, which redirects the user to the LWA website to enter their Amazon credentials for authorization.

To implement an LWA consent request

Redirect the user to LWA at https://www.amazon.com/ap/oa and append the following URL-encoded parameters to the URL:

  • client_id: The client ID for the device. To locate your client ID, see Locate your client ID and client secret.
  • scope:
    • alexa:all: Specifies the AVS permission level.

    • alexa:voice_service:pre_auth: Specifies the AVS-hosted splash screen permission level.

  • scope_data: A JSON structure that includes productID and deviceSerialNumber and is bound to the alexa:all scope.
    • productID: The product type ID for this type of device, as specified during the product registration process on the Amazon developer portal.
    • deviceSerialNumber: A unique identifier for the device, for example, a serial number or MAC address.

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

<pre>
{
  "alexa:all": {
    "productID": "{{STRING}}",
    "productInstanceAttributes": {
        "deviceSerialNumber": "{{STRING}}"
    }
  }
}

</pre>
  • response_type: Specifies the response type that you expect back from LWA. Supported value: code (Authorization Code Grant).
  • redirect_uri: Specifies one of the return URIs that you added to your app security profile in the developer portal.
  • state: An opaque value used by your device to maintain state between the request and the response and prevents cross-site request forgery. The authorization service includes this value when redirecting the user back to the client. For more details, see Cross-site Request Forgery.

The following example shows a sample authorization code grant request:

https://www.amazon.com/ap/oa?client_id=amzn1.application-oa2-client.b91a4d2fd2f641f2a15ea469&scope=alexa%3Avoice_service%3Apre_auth+alexa%3Aall&scope_data=%7B%22alexa%3Aall%22%3A%7B%22productID%22%3A%22Speaker%22%2C%22productInstanceAttributes%22%3A%7B%22deviceSerialNumber%22%3A%2212345%22%7D%7D%7D&response_type=code&state=6042d10f-6bcd-49&redirect_uri=https%3A%2F%2Flocalhost

Locate your client ID and client secret

To locate your client ID and client secret

  1. With your Amazon developer credentials, log in to the developer console.
  2. Under Alexa Voice Service, click Get Started >, and then click Edit next to your registered product or choose to create a new product.
  3. From the left navigation, select Security Profile, and view both the Client ID and Client Secret for your product.

Receive the LWA response with the authorization code

After LWA authenticates the user, LWA redirects the user to the redirect_uri provided in the consent request. The response from LWA includes an authorization code.

Sample Authorization Code Grant response

https://localhost:3000/authresponse?code=ANEctBuBjzro&scope=alexa%3Aall&state=6042d10f-6bcd-49

Next, your web service leverages the returned authorization code to request an access token:

  • Send a POST request to https://api.amazon.com/auth/o2/token with the following parameters:

    HTTP header parameters

    • Content-Type: application/x-www-form-urlencoded

    HTTP body parameters

    • grant_type: authorization_code
    • code: The authorization code returned in the response.
    • client_id: The client ID for the device. To locate your client ID, see Locate your client ID and client secret.
    • client_secret: The client secret for the device. To locate your client ID, see Locate your client ID and client secret.
    • redirect_uri: One of the return URIs that you added to your app security profile when signing up.

    Sample Request

    POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

grant_type=authorization_code&code=ANBzsjhYZmNCTeAszagk&client_id=amzn1.application-oa2-client.b91a4d2fd2f64&client_secret=6963038c1c2063c33ab9eedc0cf8&redirect_uri=https%3A%2F%2Flocalhost

    Sample Response

    HTTP/1.1 200 OK

{
    "access_token": "Atza|IQEBLjAsAhRBejiZKPfn5HO2562GBt26qt23EA",
    "expires_in": 3600,
    "refresh_token": "Atzr|IQEBLzAtAhUAibmh-1N0EsdqwqwdqdasdvferrE",
    "token_type": "bearer"
}

    Securely transfer the access and refresh tokens to the device.

Exchange the refresh token for a new access token

The access token is valid for one hour. When the access token expires or is about to expire you can exchange the refresh token for new access and refresh tokens. If the token exchange fails, your device should retry the exchange with an exponential back-off. Create a new connection to AVS after receiving and updating the tokens.

  • Send a POST request to https://api.amazon.com/auth/o2/token with the following parameters:

    HTTP Header Parameters

    • Content-Type: application/x-www-form-urlencoded

    HTTP Body Parameters

    Sample Request

    POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

grant_type=refresh_token&refresh_token=Atzr%7CIQEBLzAtAhUAibmh-1N0E&client_id=amzn1.application-oa2-client.b91a4d2fd2f6&client_secret=6963038c1c2063c33ab9eedc0cf822

    Sample Response

    HTTP/1.1 200 OK

{
    "access_token": "Atza|IQEBLjAsAhQ3yD47Jkj09BfU_qgNk4",
    "expires_in": 3600,
    "refresh_token": "Atzr|IQEBLzAtAhUAibmh-1N0EVztZJofMx",
    "token_type": "bearer"
}