@amazon-devices/keplerscript-identity-lwa-lib

The Kepler Login with Amazon (LWA) API provides functionality that allows you to protect your customer information by leveraging the user authentication system used by Amazon.com. Before you add LWA to your Kepler app, you must register your app with LWA.

To learn more about what is LWA and how it works, see Login with Amazon Documentation.

Prerequisites

The following list shows the items you need before you can add LWA to your Kepler app:

• Kepler SDK installed on your computer.
• Amazon Developer Account.
• An existing Kepler app. You can download the Vega Video Sample App to use as a template for your app.
• Your app must be registered with Login with Amazon. For more information, see Register for Login with Amazon.
• An API key for your app. For more information, see Get an API key
• Kepler-supported Fire TV Stick. LWA does not support the Kepler Virtual Device so you need to test your integration on a device.

Get an API key

To use LWA with your app, you need to provide the app's API key. The API key is an identifier that the Amazon Authorization Manager uses to identify your app to the LWA authorization service. You need different API Keys for debug and production apps. You generate the API key using the app package ID and the app MD5 and SHA256 Signatures. While the package ID for the debug and production versions of your app is the same, you use different procedures to retrieve the MD5 and SHA256 Signatures. To retrieve the signature for a debug app, see MD5 and SHA256 Signatures for debug apps. For production apps, see MD5 and SHA256 Signatures for production apps.

Follow the steps below to create an API ey and add it to your LWA account:

1. Open the Amazon Appstore Developer Console and log in to your account.
2. Create or open an existing security profile. For more information, see LWA docs.
3. Add an API key for your Kepler app.
   1. Select Android/Kindle Settings.

   2. Go to Add an API Key. Enter the following information:

      • API Key Name - create a name to identify your app.
      • Package - enter your package ID, such as com.mycompany.myapp.
      • MD5 Signature - enter the MD5 signature.
      • SHA256 Signature - enter the SHA256 signature.

MD5 and SHA256 Signatures for debug apps

1. Connect the Fire TV Stick to your development machine.
   1. Open a terminal shell and run the vda devices command.
   2. Confirm the device serial number is listed in the output.

      Copy code Copied to clipboard.

      .

       vda devices
       List of devices attached
       G4N33M33333333TA    device
      

2. In the terminal, run vpm info <package_name>. Replace with your app's package name. You can find the package name in your manifest.toml file.

   Copy code Copied to clipboard.

    [package]
    id = "com.amazon.identity.lwa.authorizationmanager.service" ==> package_name
   

3. Locate the signature information.

   1. In the command output, find the "Signers info" section.

   2. Note down both the MD5 and SHA256 signatures for any one of the signers. For the SHA256 signature, there are two lines in the output. Connect the lines with a :. For example, if your output shows this for SHA256:

      Copy code Copied to clipboard.

       17:6c:1b:d5:24:d6:0d:6c:e7:88:fd:9c:61:09:c2:01
       b2:21:2a:79:66:10:c8:a7:74:64:11:d0:13:39:31
      

      The correct string for SHA256 is

      17:6c:1b:d5:24:d6:0d:6c:e7:88:fd:9c:61:09:c2:01:b2:21:2a:79:66:10:c8:a7:74:64:11:d0:13:39:31

MD5 and SHA256 Signatures for production apps

For a release, or "production", version of your app, you must create an additional API key using Appstore’s MD5 and SHA256 signatures and store it in your app's manifest.toml file. This is also required for apps that use In-App Purchasing (IAP) or Live App Testing (LAT).

You can find your Appstore certificate hash values in the Developer Console to create the API keys for existing apps. Go to My apps > select your app's current version > Upload Your App File > Appstore Certificate Hashes.

Extract clientID from API key

The API key is a JWT (JSON Web Token). You can decode this key to find your clientID, which is used for backend services.

Use any JWT decoding tool to decode the API key.

Setup

1. Add the following library dependency to the dependencies section of your package.json file.

   Copy code Copied to clipboard.

    "dependencies": {
      "@amazon-devices/keplerscript-identity-lwa-lib": "~0.0"
    }
   

2. In your manifest.toml, add the following privilege and replace api_key with the API key that you obtained earlier.

   Copy code Copied to clipboard.

    [wants]
    [[wants.service]]
    id = "com.amazon.identity.lwa.authorizationmanager.service"
   
    [[extras]]
    key = "api_key"
    value = "xyz"
   

Apps that use IAP or LAT have separate requirements for API keys. See the Production apps section above for details.

Usage

Example: Authorize a user

The following code example demonstrates how to integrate the Authorize call into your React Native components to initiate user authorization flow and obtain access tokens and user details.

import {
  AuthorizationManager,
  AuthorizeCallbacks,
  AuthorizeCancellationReason,
  AuthorizeSuccessParams,
  GrantTypeName,
  ScopeName
} from '@amazon-devices/keplerscript-identity-lwa-lib';

/**
 * Define callback functions to handle the result of the authorization process.
 */
const authorizeCallbacks: AuthorizeCallbacks = {
  // Called when the authorization succeeds
  authorizeSuccess: (authParams) => {
    console.log('Authorization successful:', authParams);
    // Handle the successful response:
  },

  // Called when authorization fails due to an error
  authorizeFailure: (error) => {
    console.error('Authorization failed:', error);
    // Handle the failure scenario:
  },

  // Called when the user or system cancels the authorization
  authorizeCancel: (cancelReason) => {
    console.log('Authorization cancelled:', cancelReason);
    // Handle cancellation:
  }
};

// Step 1: Define your authorization request parameters.
const authorizeRequest: AuthorizeRequest = {
  scopes: [
    { name: ScopeName.PROFILE },         // Request user's profile information
    { name: ScopeName.POSTAL_CODE }      // Request user's postal code.
  ],

  // Optional: Use only when performing an Authorization Code flow with PKCE
  // PKCE (Proof Key for Code Exchange) improves security for public clients.
  // e.g., 'AUTH_CODE' or 'ACCESS_TOKEN'
  // If not provided, it defaults to 'ACCESS_TOKEN'.
  grantType: GrantTypeName.ACCESS_TOKEN,
  codeChallenge: 'your-code-challenge',           // <-- Replace with actual PKCE code challenge
  codeChallengeMethod: 'your-code-challenge-method' // e.g., S256 for SHA-256, or plain.
};

// Step 2: Trigger the authorization request
AuthorizationManager.authorize(
  authorizeRequest,
  authorizeCallbacks
);

Example: Get an authorization token

The following code example demonstrates how to integrate the GetToken call into your React Native components to retrieve authorization tokens for specified scopes.

import {
  AuthorizationManager,
  GetTokenCallbacks,
} from '@amazon-devices/keplerscript-identity-lwa-lib';

// Define callback functions to handle the result of the getToken operation.
const getTokenCallbacks: GetTokenCallbacks = {
  // When the token is successfully retrieved, this function is called.
  getTokenSuccess: function (access_token: any): void {
    console.log('getTokenSuccess', JSON.stringify(access_token));
    // Place any logic here to use the received token--such as authenticating API requests or storing it securely.
  },
  // If there is an error during the token retrieval process, this function is called.
  getTokenFailure: function (category: any): void {
    console.log('getTokenFailure', JSON.stringify(category));
    // Add logic here to handle token retrieval failure--such as showing an error message or retrying the operation.
  },
};

// To start the token retrieval process, call the getToken method from AuthorizationManager.
// This method takes the callback functions defined above to manage success and failure outcomes.
AuthorizationManager.getToken(getTokenCallbacks);

Example: Get user details

The following code example demonstrates how to integrate the GetUser call into your React Native components to fetch and display user profile information.

import {
  AuthorizationManager,
  GetUserCallbacks,
} from '@amazon-devices/keplerscript-identity-lwa-lib';

// Define callback functions to handle the result of the getUser operation.
const getUserCallbacks: GetUserCallbacks = {
  // When user information is successfully retrieved, this function is executed.
  getUserSuccess: (userInfo) => {
    console.log('User info retrieved:', userInfo);
    // Add any additional logic to handle the user information--such as displaying it on the UI or storing it for session management.
  },
  // If there is an error retrieving user information, this function is called.
  getUserFailure: (error) => {
    console.error('Failed to retrieve user info:', error);
    // Handle user retrieval failure by displaying an error message or taking appropriate corrective action.
  },
};

// Call the getUser method from AuthorizationManager to trigger the user profile retrieval process.
// This method takes the callback functions defined above for handling success and failure outcomes.
AuthorizationManager.getUser(getUserCallbacks);

Example: Sign out a user

The following code example demonstrates how to integrate the Signout call into your React Native components to allow users to securely sign out from their accounts.

import {
  AuthorizationManager,
  SignOutCallbacks,
} from '@amazon-devices/keplerscript-identity-lwa-lib';

// Define callback functions to handle the result of the sign-out process.
// These functions are called once the sign-out operation is complete.
const signOutCallbacks: SignOutCallbacks = {
  // If the sign-out is successful, this function is executed.
  signOutSuccess: () => {
    console.log('Sign out successful');
    // Additional logic to handle post sign-out actions can be placed here--such as redirecting the user or clearing session data.
  },
  // If the sign-out fails, this function is executed.
  signOutFailure: (error) => {
    console.error('Sign out failed:', error);
    // Include error-handling logic here--such as displaying an error message to the user or retrying the operation.
  },
};

// To trigger the sign-out process, call the signOut method from AuthorizationManager.
// This method takes the callback functions defined above.
AuthorizationManager.signOut(signOutCallbacks);

Modules

• index
• turbo-modules/KeplerLWATurboModuleManager
• turbo-modules/KeplerLWATurboModuleManager
• turbo-modules/keplerLWATurboModules
• turbo-modules/keplerLWATurboModules
• types/LWADataTypes
• types/LWADataTypes

Last updated: Oct 03, 2025