Authorize from a Companion Site

This guide is for product manufacturers that use a website to authorize users. If your users will register your product with a companion mobile app, please see Authorizing from a Companion App.

Types of Authorization

Login with Amazon (LWA) supports two types of authorization:

  • Implicit Grant - A client ID is sent and an access token is returned
    • Advantages: Relies on client-side scripting; easier to implement
    • Disadvantages: The access token expires and the user is required to reauthenticate hourly
  • Authorization Code Grant - A client ID and client secret are sent and an access and refresh token are returned
    • Advantages: More secure; indefinitely request new access tokens using the refresh token
    • Disadvantages: Requires server-side scripting; more difficult to implement

If you are able to implement server-side scripting, then the authorization code grant is recommended.

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

A consent request is created when a user clicks the Login button on your companion site. The user is redirected to the LWA website where they are prompted to enter their Amazon credentials and authorize their instance of the product to access AVS on their behalf. This is how the consent request is constructed:

  • 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, 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 values: token (Implicit Grant) and 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 Requests

Implicit Grant

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=token&state=6042d10f-6bcd-49&redirect_uri=https%3A%2F%2Flocalhost

Authorization Code Grant

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.

Implicit Grant

The response from LWA includes an access token. URL-decode the access token in the response (Atza%7C... → Atza|...) and securely transfer it to the user's product.

Sample Implicit Grant Response

https://localhost:3000/authresponse#access_token=Atza|IwEBIP1l6K6yU9NySgMm&token_type=bearer&expires_in=3600&scope=alexa%3Aall&state=6042d10f-6bcd-49

Authorization Code Grant

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 (Authorization Code Grant Only)

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. A new connection to AVS should be made only after the tokens are successfully received and updated.

  • 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