Authorize from a Companion Site

This page describes how to implement Alexa Voice Service (AVS) authorization through a website. If your users will register your product with a companion mobile app, please see Authorizing from a Companion App.

About Authorization Code Grant and Login with Amazon (LWA)

Login with Amazon (LWA) supports the Authorization Code Grant form of authorization. For an Authorization Code Grant, send the client ID and client secret to LWA, and LWA returns access and a refresh token.

Authorization Flow

This diagram illustrates the data flow to obtain an access token using a companion site:

Click to enlarge
  1. The product registers with your web service. Registration should include information about your product, such as: device serial number (DSN) and product ID.
  2. The user navigates to your companion site and clicks Login. On click, the user is redirected to LWA. For information on how to construct the URL, see Create a Login with Amazon Consent Request.
  3. The user is prompted to enter their Amazon credentials and grant access for the product to communicate with Alexa Voice Service (AVS) on their behalf.
  4. (a) The user is redirected back to your companion site.
    (b) An access token or auth token is sent to your web service.
  5. Auth code, client ID, and client secret are sent from your web service to LWA.
  6. Access and refresh tokens are sent to your web service.
  7. Refresh token, client ID, and client secret are exchanged for a new access token hourly or when the existing token is about to expire. If the token exchange fails, your client is expected to retry with an exponential back-off.
  8. The access token is securely transferred from your web service to the product. A new connection to AVS should only occur after the new tokens are successfully received and updated.

Create a Login with Amazon 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. LWA prompts them to enter their Amazon credentials and authorize their instance of the product to access AVS on their behalf. Construct the consent request with the following parameters:

  • Redirect the user to Login with Amazon at https://www.amazon.com/ap/oa with the following URL-encoded parameters appended:

    • client_id: The product's client ID. To access this information, navigate to Amazon's Developer Console. After you've logged in, click Get Started > under Alexa Voice Service, and then click Edit next to a registered product (or create a new one). From the left navigation select Security Profile. This page contains both Client ID and Client Secret for your product.
    • scope:
      • alexa:all: AVS permission level.
      • alexa:voice_service:pre_auth: AVS hosted splash screen permission level.
    • scope_data: A JSON structure that includes productID and deviceSerialNumber. It is bound to the alexa:all scope.
      • productID: The product type ID for this type of product. The product type ID was specified as part of the product registration process on the Amazon developer portal.
      • deviceSerialNumber: A unique identifier for the product. For example, this could be a serial number or MAC address.
      {
  "alexa:all": {
    "productID": "{{STRING}}",
    "productInstanceAttributes": {
        "deviceSerialNumber": "{{STRING}}"
    }
  }
}
    • 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's security profile in the developer portal.
    • state: An opaque value used by your client to maintain state between the request and the response. The authorization service will include this value when redirecting the user back to the client. It is also used to prevent cross-site request forgery. For more information, see Cross-site Request Forgery.

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

Login with Amazon Returns a Response to Your Registration Website

After the user is authenticated, the user is redirected 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 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 that was returned in the response.
    • client_id: The product's client ID. To access this information, navigate to Amazon's Developer Console. After you've logged in, click Get Started > under Alexa Voice Service, then click Edit next to a registered product (or create a new one). From the left navigation select Security Profile. This page contains both Client ID and Client Secret for your product.
    • client_secret: The product's client secret. To access this information, navigate to Amazon's Developer Console. After you've logged in, click Get Started > under Alexa Voice Service, then click Edit next to a registered product (or create a new one). From the left navigation select Security Profile. This page contains both Client ID and Client Secret for your product.
    • redirect_uri: One of the return URIs that you added to your app's 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 user's product.

Use the Access Token to Make Alexa Voice Service API Calls

The access token must be included in the header of each request. Specifically, create an Authorization header and give it the value Bearer {{access_token}}.

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 client is expected to retry 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

    • grant_type: refresh_token
    • refresh_token: The URL-encoded refresh token returned with the last request for a new access token.
    • client_id: To access this information, navigate to Amazon's Developer Console. After you've logged in, click Get Started > under Alexa Voice Service, then click Edit next to a registered product (or create a new one). From the left navigation select Security Profile. This page contains both Client ID and Client Secret for your product.
    • client_secret: The website's client secret. To access this information, navigate to Amazon's Developer Console. After you've logged in, click Get Started > under Alexa Voice Service, then click Edit next to a registered product (or create a new one). From the left navigation select Security Profile. This page contains both Client ID and Client Secret for your product.

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

Resources

Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment