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)
- Authorization Flow
- Create a Login with Amazon Consent Request
- Login with Amazon Returns a Response to Your Registration Website
- Use the Access Token to Make Alexa Voice Service API Calls
- Exchange the Refresh Token for a New Access Token
- Resources
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:

- The product registers with your web service. Registration should include information about your product, such as: device serial number (DSN) and product ID.
- 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.
- 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.
- (a) The user is redirected back to your companion site.
(b) An access token or auth token is sent to your web service. - Auth code, client ID, and client secret are sent from your web service to LWA.
- Access and refresh tokens are sent to your web service.
- 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.
- 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:
alexa:voice_service:pre_auth
scope and remove your existing splash screen. All new products are required to utilize the AVS hosted splash scope.-
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 includesproductID
anddeviceSerialNumber
. It is bound to thealexa: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.
Note: This is a sample scope object before it is URL-encoded. Use the sample requests below for reference.{ "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
Tip: Alternatively,client_id
andclient_secret
may be passed in theAuthorization
header, as a base 64 encoding ofclient_id:client_secret
. See Access Token Request for additional information and examples.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
Note: Alternatively,client_id
andclient_secret
may be passed in theAuthorization
header, as a base 64 encoding ofclient_id:client_secret
. See Access Token Request for additional information and examples.Sample Response
HTTP/1.1 200 OK { "access_token": "Atza|IQEBLjAsAhQ3yD47Jkj09BfU_qgNk4", "expires_in": 3600, "refresh_token": "Atzr|IQEBLzAtAhUAibmh-1N0EVztZJofMx", "token_type": "bearer" }