Using the LWA Web API

II: Integrate LwA in your apps

→

Warning: You are viewing an old version of the DRS docs. To access the new APIs, see Dash Replenishment Overview.

Note: If you are developing a hybrid solution (e.g. Cordova, Xamarin) please contact your Amazon point of contact.

To access the Dash Replenishment Service (DRS) APIs, your web application needs to obtain a Login With Amazon (LWA) access token that grants access to the APIs on behalf of the product’s user.

Follow the instructions below to use the Login with Amazon web SDK to pass the Login with Amazon authorization code, client ID, and redirect URI to your web application. It can then use this data to obtain the access token needed to make calls to DRS REST APIs.

Types of Authorization
Create a Security Profile
Integrate with the LWA SDK for JavaScript
Obtain Refresh and Access Tokens using Authorization Code Grant
Request New Refresh and Access Tokens
Call DRS APIs
Next Step

Types of Authorization

LWA supports two types of authorization: Implicit Grant and Authorization Code Grant. However, DRS requires the Authorization Code Grant.

Create a Security Profile

Go to the Login with Amazon console and select one of the security profiles. If you do not have a security profile, follow the steps in the Create an LWA Security Profile guide to create one.
In the Manage section, under your security profile, select Web Settings.
Click on the Edit button and fill in the Allowed Origins and the Allowed Returns URLs fields. These must match the domain hosting your website (for example, http://www.example.com and http://www.example.com/login).

Integrate with the LWA SDK for JavaScript

The Login with Amazon SDK for JavaScript handles all aspects of integrating Login with Amazon into your website.

Add the following code to your website where you would like the Login With Amazon button to appear. You can select from a variety of buttons and choose the image that best fits your website. See the Login with Amazon Style Guidelines for best practices and a list of images to choose from. For the purposes of this guide, this must be an HTTPS website:
```
<a href="#" id="LoginWithAmazon">
<img border="0" alt="Login with Amazon"
   src="https://images-na.ssl-images-amazon.com/images/G/01/lwa/btnLWA_gold_156x32" type="png"
   width="156" height="32" />
</a>
```
(Optional) Add the following link to your website where you would like a "Logout" prompt to appear:
```
<a id="Logout">Logout</a>
```
Refresh the page to confirm that the button now appears on your website.

Add the following code after the opening <body> in your page to load the JavaScript into your page:

<div id="amazon-root"></div>
<script type="text/javascript">
window.onAmazonLoginReady = function() {
      amazon.Login.setClientId('YOUR-CLIENT-ID');
  };
  (function(d) {
      var a = d.createElement('script');
      a.type = 'text/javascript';
      a.async = true;
      a.id = 'amazon-login-sdk';
      a.src = 'https://api-cdn.amazon.com/sdk/login1.js';
      d.getElementById('amazon-root').appendChild(a);
  })(document);
</script>

Replace YOUR-CLIENT-ID with your Client ID from the Security Profile created previously in the Login With Amazon console.

Add the following JavaScript after the Login with Amazon button on your site:

<script type="text/javascript">
document.getElementById('LoginWithAmazon').onclick = function() {
    var deviceModel = 'YOUR-DEVICE-MODEL-ID';
    var serialNo = 'YOUR-DEVICE-SERIAL-NO';
    var drsScope = 'dash:replenish';
    var scopeData = new Object();
    scopeData[drsScope] = {
        device_model: deviceModel,
        serial: serialNo
    };
    var options = {
        scope: drsScope,
        scope_data: scopeData,
        response_type: 'code'
    };
    amazon.Login.authorize(options, 'REDIRECT-URI');
    return false;
};
</script>

Replace YOUR-DEVICE-MODEL-ID with the device model ID for your device. The device type ID was specified as part of the device registration process on the Amazon developer portal.
Replace YOUR-DEVICE-SERIAL-NO with the key that uniquely identifies the instance of a product. For example, this could be a serial number or MAC address. Note: The device model ID and device serial must not exceed 64 characters and must use the following character set: [A-Z], [a-z], [0-9], "-", "+", "_".
Replace REDIRECT-URI with one of the Allowed Return URLs, added to the security profile you created previously.

Include "should_include_non_live": true in the scopeData[drsScope] object if the marketplace has not been certified yet. This parameter, if true, allows customers to access the DRS flow using device capabilities that have not yet been certified by Amazon. You can use this parameter to test your system while awaiting Amazon certification. This flag must not be passed in by your released app in production.

<script type="text/javascript">
document.getElementById('LoginWithAmazon').onclick = function() {
    var deviceModel = 'YOUR-DEVICE-MODEL-ID';
    var serialNo = 'YOUR-DEVICE-SERIAL-NO';
    var drsScope = 'dash:replenish';
    var scopeData = new Object();
    scopeData[drsScope] = {
        device_model: deviceModel,
        serial: serialNo,
        should_include_non_live: true,
        is_test_device: true
    };
    var options = {
        scope: drsScope,
        scope_data: scopeData,
        response_type: 'code'
    };
    amazon.Login.authorize(options, 'REDIRECT-URI');
    return false;
};
</script>

The following table summarizes the configuration required for should_include_non_live and is_test_device in 3 different phases: during testing, when you submit for certification and when you go live in production.

Attribute	Test	Certification	Production
`should_include_non_live`	`true`	`true`	`false`
`is_test_device`	`true`	`false`	`false`

Warning: You will not be able to test devices without setting the is_test_device flag to true, but you must set it to false in production.

You can now refresh the page and click on the Login With Amazon button to authenticate.

When the authentication is completed, the user is redirected to the REDIRECT-URI you chose at the beginning of the flow. The service will append the authorization_code to it.

Example:

https://myredirecturi.domain/index.html?code=ANJWODERsVtbvwKDOYfu&scope=dash%3Areplenish

You should now use the code= returned by the service to obtain the access and refresh tokens.

Obtain Refresh and Access Tokens using Authorization Code Grant

Note: Requesting an access token and refresh token for the native APIs is different. If you are developing your product using the Android or iOS SDK make sure to check the relevant pages.

After the user is authenticated, the user is redirected to the URI that you replaced with the REDIRECT-URI placeholder in the previous section.

Sample Authorization Code Grant Response

https://www.example.com/login?code=ANdNAVhyhqirUelHGEHA&scope=dash:replenish

Next, your service leverages the returned authorization code to ask for 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 website’s client ID. This information can be found on the Amazon developer portal’s Login With Amazon page.
client_secret: The website’s client secret. This information can be found on the Amazon developer portal’s Login With Amazon page.
redirect_uri: Should match one of the Allowed Return URLs, added to the security profile created previously.

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

Transfer the refresh token and access token to your user’s product.

Request New Refresh and Access Tokens

Note: Requesting an access token and refresh token for the native APIs is different. If you are developing your product using the Android or iOS SDK make sure to check the relevant pages.

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 a new 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: refresh_token
refresh_token: The refresh token used to request new access tokens.
client_id: The website’s client ID. This information can be found on the Amazon developer portal’s Login With Amazon page.
client_secret: The website’s client secret. This information can be found on the Amazon developer portal’s Login With Amazon page.
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=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"
}

Call DRS APIs

It is now possible to call all DRS REST APIs. When making a request, add an Authorization header and give it the following value:

Bearer <access_token>

Use the access_token obtained previously.

Next Step

Next, we will look at integrating Login with Amazon in your other companion apps.

To create…	Use
A native Android app	LwA SDK for Android
A native iOS app	LwA SDK for iOS
A web app or hybrid app (e.g. Cordova)	LwA for Web

If you have integrated LwA already, you may move onto the API section of our tutorial.

Last updated: Aug 07, 2018