Authorize an AVS Device Through a Companion App

Use LWA SDK for Android to pass a LWA authorization code to your device, which your device can then use to obtain refresh and access tokens needed to make calls to AVS.

• Register a device in the Amazon developer console and generate an API key for your device. For instructions on how to create an account and register a device see Getting Started with AVS.
• Navigate to Login with Amazon for Android Overview and follow the instructions on the page.
• Then complete the following steps to obtain an LWA access token to use with AVS:

1. Import the Login with Amazon API to your source file. To import the Login with Amazon API, add the following import statements to your source file:

   import com.amazon.identity.auth.device.AuthError;
   import com.amazon.identity.auth.device.api.authorization.AuthCancellation;
   import com.amazon.identity.auth.device.api.authorization.AuthorizationManager;
   import com.amazon.identity.auth.device.api.authorization.AuthorizeListener;
   import com.amazon.identity.auth.device.api.authorization.AuthorizeRequest;
   import com.amazon.identity.auth.device.api.authorization.AuthorizeResult;
   import com.amazon.identity.auth.device.api.authorization.ScopeFactory;
   import com.amazon.identity.auth.device.api.workflow.RequestContext;
   

2. Initialize the RequestContext.

   Declare a RequestContext member variable and create a new instance of the class. To create the instance, pass in the current app context to the static factory method. The best place to initialize the RequestContext is in the onCreate method of your Activity. For example:

   private RequestContext mRequestContext;
   
   @Override
   protected void onCreate(Bundle savedInstance) {
       super.onCreate(savedInstance);
       mRequestContext = RequestContext.create(this);
   }
   

3. Create an AuthorizeListenerImpl.

   AuthorizeListenerImpl extends the AuthorizeListener abstract class and processes the result of the authorize call. It contains three methods: onSuccess, onError, and onCancel. The AuthorizeResult object passed into the onSuccess method contains the values needed to obtain an authorization token.

   private class AuthorizeListenerImpl extends AuthorizeListener {
   
       /* Authorization was completed successfully. */
       @Override
       public void onSuccess(final AuthorizeResult authorizeResult) {
       }
   
       /* There was an error during the attempt to authorize the application. */
       @Override
       public void onError(final AuthError authError) {
       }
   
       /* Authorization was cancelled before it could be completed. */
       @Override
       public void onCancel(final AuthCancellation authCancellation) {
       }
   }
   

4. Create an instance of AuthorizeListenerImpl and register it.

   Create an instance of your AuthorizeListenerImpl and register it with your RequestContext instance. When the AuthorizeManager.authorize call is made, your RequestContext instance invokes the appropriate callback method in your AuthorizeListener with the result of the authorize request. The best place to register your AuthorizeListenerImpl instance is in the onCreate method.

   @Override
   protected void onCreate(Bundle savedInstance) {
     super.onCreate(savedInstance);
     mRequestContext = RequestContext.create(this);
     mRequestContext.registerListener(new AuthorizeListenerImpl());
   }
   

5. Override the onResume method.

   Override the onResume method in your Activity. Call super.onResume() as well as the onResume method on your RequestContext instance. This notifies the RequestContext to invoke your AuthorizeListener when your app resumes if a callback is ready from your AuthorizeManager.authorize call.

   @Override
   protected void onResume() {
       super.onResume();
       mRequestContext.onResume();
   }
   

6. Call AuthorizeManager.authorize.

   In the onClick handler for your Login with Amazon button, call authorize to prompt the user to log in and authorize your app. This method authorizes the user in one of the following ways:

   • Switches to the system browser and lets the user sign in and consent to the requested information.

   • Switches to web view in a secure context to let the user sign in and consent to the requested information.


   This secure context is available through the Amazon Shopping app on Android devices. Amazon devices running Fire OS, for example Kindle tablets and Fire TV devices, always use this option even if there is no Amazon Shopping app on the device. Because of this, if the user is already signed in to the Amazon Shopping app, this API skips the sign-in page, leading to a Single Sign On experience for the user.

   Amazon authorizes your app for one or more data sets known as scopes. Scopes are an OAuth mechanism for a client to tell an authorization server what resource permissions they need. You pass an array of scopes as a parameter to the authorize method.

   The first time a user logs in to your app, they receive a prompt asking for consent to access to the required data before proceeding. When used with AVS, LWA requires the alexa:all scope. The alexa:voice_service:pre_auth scope enables the AVS Hosted Splash for the user.

   Important: To use the AVS-hosted splash, you must include the alexa:voice_service:pre_auth scope, and remove your existing splash screen. All new devices must use the AVS-hosted splash scope.

   The call to authorize is asynchronous, and Amazon invokes your AuthorizeListenerImpl instance with the result of your call.

   The following example adds the following options:

   • scopeData is extra data that includes the product type ID (PRODUCT_ID) and unique DSN (PRODUCT_DSN), that binds to the alexa:all scope.
   • A constant which specifies that the authorization code should be returned.
   • The code challenge. For Base64 URL encoding we recommend using Android’s Base64 library with the following flags: Base64.NO_PADDING, Base64.URL_SAFE, and Base64.NO_WRAP.
   • The Code Challenge encoding method (S256).
   • The single-use authorization code you’ve obtained is valid for five minutes and a single use.

   private RequestContext mRequestContext;
   private static final String PRODUCT_ID = "INSERT YOUR PRODUCT ID FROM AMAZON DEVELOPER CONSOLE";
   private static final String PRODUCT_DSN = "INSERT UNIQUE DSN FOR YOUR DEVICE";
   private static final String CODE_CHALLENGE = "INSERT CODE CHALLENGE FROM DEVICE FOR THIS REQUEST";
   private static final String CODE_CHALLENGE_METHOD = "S256";
   
   @Override
   protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       mRequestContext = RequestContext.create(this);
       mRequestContext.registerListener(new AuthorizeListenerImpl());
   
       // Find the button with the login_with_amazon ID
       // and set up a click handler
       mLoginButton = (Button) findViewById(R.id.login_with_amazon);
       mLoginButton.setOnClickListener(new OnClickListener() {
           @Override
           public void onClick(View v) {
               final JSONObject scopeData = new JSONObject();
               final JSONObject productInstanceAttributes = new JSONObject();
   
               try {
                   productInstanceAttributes.put("deviceSerialNumber", PRODUCT_DSN);
                   scopeData.put("productInstanceAttributes", productInstanceAttributes);
                   scopeData.put("productID", PRODUCT_ID);
   
                   AuthorizationManager.authorize(new AuthorizeRequest.Builder(mRequestContext)
                       .addScopes(ScopeFactory.scopeNamed("alexa:voice_service:pre_auth"),
                               ScopeFactory.scopeNamed("alexa:all", scopeData))
                       .forGrantType(AuthorizeRequest.GrantType.AUTHORIZATION_CODE)
                       .withProofKeyParameters(CODE_CHALLENGE, CODE_CHALLENGE_METHOD)
                       .build());
               } catch (JSONException e) {
                   // handle exception here
               }
           }
       });
   }
   

7. Implement onSuccess for your AuthorizeListenerImpl.

   Retrieve the authorization code, redirect URI, and client id from the AuthorizeResult to be sent securely to your device.

   private class AuthorizeListenerImpl extends AuthorizeListener {
       @Override
       public void onSuccess(final AuthorizeResult authorizeResult) {
           final String authorizationCode = authorizeResult.getAuthorizationCode();
           final String redirectUri = authorizeResult.getRedirectUri();
           final String clientId = authorizeResult.getClientId();
           // Securely send the authorization code, redirectUri, and clientId to the device
       }
       // …
       // Other methods from AuthorizeListener
   }
   

8. After the device receives the authorization code, client ID, and redirect URI, the device should call LWA to exchange the authorization code for access and refresh tokens. When making the call, the device needs to send a POST request to https://api.amazon.com/auth/O2/token and pass in the following parameters:

   • grant_type: authorization_code
   • code: The authorization code received from the Android app.
   • redirect_uri: The redirect URI received from the Android app.
   • client_id: The client ID received from the Android app.
   • code_verifier: The code verifier that was initially generated by the device.

   The response includes the following values:

   • access_token: The access token.
   • refresh_token: The refresh token.
   • token_type: bearer
   • expires_in: The number of seconds for which the access token is still valid.

9. When the access token has expired or is about to expire, exchange the refresh token for new access and refresh tokens. Create a new connection to AVS after receiving and updating the tokens. If the token exchange fails, your device should retry the exchange with an exponential back-off. To do the exchange, POST to https://api.amazon.com/auth/O2/token with the following parameters:

   • grant_type: refresh_token
   • refresh_token: The refresh token.
   • client_id: The client ID received from the Android app.

   The response includes the following values:

   • access_token: The access token.
   • refresh_token: The refresh token.
   • token_type: bearer
   • expires_in: The number of seconds for which the access token is still valid.