LWA Account Linking (Pull)

Account linking refers to any process that connects a Prime Gaming customer's player identity with their Amazon identity. A player identity is however you uniquely identify your players, usually through a game, studio, or publisher account. This is sometimes referred to as a "game account". Similarly, a customer's Amazon identity is verified by their Amazon account. By linking these two accounts, we ensure that the person claiming an offer on the Prime Gaming website is the same person receiving the offer's content.

To link game accounts with Amazon accounts in a pull integration, Prime Gaming recommends Login with Amazon (LWA). LWA is widely used among Amazon partners, offers SDKs for implementation that follow OAuth 2.0 best practices, and lets customers connect to your platform in just a few clicks using an Amazon account. LWA for Websites is a traditional login process using a website or web service, and players will be able to link their accounts directly from the Prime Gaming offer page. LWA for Devices uses code pairing with an Amazon verification page to let customers log in from their smartphone or another device, and will require updating your game's client code. Follow the instructions below to choose and implement the best solution for your game.

Option 1: LWA for Websites

Recommended:

• For multi-platform or PC games
• If you have an existing web-based account or identity system, regardless of your game's platform(s)

Prerequisites:

• Access to a web platform that you own where you can deploy code
• A database or other persistence layer where you can securely save a player's LWA metadata
• The ability to securely and uniquely identify a player, i.e. with a game account or profile
• At least one Amazon account with an active Prime subscription for basic testing; the free trial works for this purpose if needed
• (recommended) Basic working knowledge of the OAuth 2.0 specification, especially Authorization Code Grants

Step-by-step instructions

The following is an overview of how to set up and use LWA for Websites in a Prime Gaming context. For more specific integration details, please refer to the official LWA for Websites docs.

1. Create a Security Profile and register your app with LWA. (main article: Register for Login with Amazon) For a basic LWA for Websites implementation, you'll only need a single Security Profile. Navigate to the "Web Settings" tab to register your app.
   • If this is your first time using the Developer Console, you'll need to set up an account; it's recommended to use a company-wide account instead of linking it to a particular person. Once created, you can add other users with specific permissions.
   • We recommend using a single Security Profile for all of your service's deployment environments (e.g. beta, staging, production). Login with Amazon only exposes its production environment, so additional profiles will all behave the same as the first.
   • If you're still designing your LWA authorization workflow and aren't sure what your Allowed Origins or Allowed Return URLs will be, you can enter any valid URL for now to register your app and get a client ID. These values can be changed later.
2. Reach out to your Prime Gaming tech contact with your LWA client ID and Security Profile ID to be allow-listed for the games::prime scope. This OAuth scope authorizes your LWA client to retrieve a user's Prime Gaming entitlements, and is required. Please allow a short turnaround time for your LWA profile and client to be allow-listed.
3. Prepare an LWA account endpoint on your website. This can be hosted on any public website your company controls. This endpoint will be used to kick off the LWA process. Users should be signed into their game account before this endpoint invokes LWA.
   • To reduce clicks, consider assigning this account linking endpoint a dedicated URL, such as /link-accounts/prime-gaming. The LWA documentation describes adding a button to your website to start the process, which is unnecessary for the Prime Gaming workflow.
   • There are several ways to structure your workflow to require a game account login before invoking Login with Amazon. If you have an existing mechanism to check for a login cookie (or equivalent) and redirect users to a sign-in page, simply put the LWA page behind that mechanism. Alternately, you can start users on a dedicated game account login form and redirect to the LWA page after they are logged in.
4. Add the LWA SDK for JavaScript to the new page and invoke its authorize() method on page load, or manually call Amazon's /ap/oa API. (main articles: Add the Login with Amazon SDK for JavaScript • Authorization Request) This will start the Login with Amazon authorization request process and send the user to an Amazon login page.
   • The scope parameter of this request should be profile games::prime (profile%20games%3A%3Aprime when URL encoded). Note the space between the two scopes.
   • As the LWA documentation notes, the SDK will open the login screen in a popup window by default. If you are automatically redirecting users through a server-side workflow, consider setting options.popup = false and handling the callback as described in the next step.
   • If you're having LWA redirect to another endpoint, include a state parameter that references the current user's player/game identity. You'll use this when receiving the callback to match that request to the right user. This parameter should also include a csrf token to prevent cross-site request forgery attacks.
   • Please note: Use of the LWA SDK assumes you have access to a host that can run server-side JavaScript. If this isn't feasible for your tech stack, you can replace the SDK invocations with direct API calls as described in Authorization Code Grant.
5. Add a method or a new endpoint to handle the authorization response (callback) from LWA. (main article: Authorization Code Grant - Server Apps) After entering their Amazon credentials, the user will be sent to the provided redirect_uri with the authorization code and any previously passed state as query parameters. If using a different endpoint than the previous step, this is where you'll use state to look up the user who initiated this workflow.
   • This redirect_uri needs to be specified as an Allowed Return URL in your LWA Security Profile.
   • Remember to handle any authorization errors that might be returned by LWA, such as configuration issues or a user denying your service's request. The LWA documentation includes a full list of potential errors.
6. Exchange the authorization code for an access token and refresh token. (main article: Authorization Code Grant - Access Token Request) You can use the LWA SDK's retrieveToken() method or make a direct POST request to the appropriate Amazon API. If you're using a browser-driven approach, you will not receive a refresh token.
   • This request supports a redirect_uri parameter, but it is usually performed as a synchronous request by the same web resource that received the callback in the previous step.
7. Use the access token to retrieve the customer's Amazon user_id. (main article: Obtain Customer Profile Information) The LWA documentation explains several approaches to this step in detail. Ultimately, the "account link" is the relationship between this ID and your player's game account.
8. Securely store the Amazon ID and LWA tokens so they can be used to make Prime Gaming API calls on this user's behalf. This is discussed in more detail in the next section, Manage Linked Accounts.
9. Redirect the user back to the Prime Gaming offer page. This URL will be provided to you during the integration process, and will stay the same for the duration of your campaign.
   • If you prefer to avoid hard-coding this URL into your service, it can be passed by the offer page as a query parameter in the original account linking URL (i.e. /link-accounts/prime-gaming?redirect=[...]). Please let your Prime Gaming contact know if you'd like it set up in this way.

Next: Manage Linked Accounts

Option 2: LWA for Devices

Recommended:

• For console-exclusive games or other platforms where text entry is limited
• If you do not have a web-based account or identity system, or have limited access to your title's web services

Prerequisites:

• A database, in-game storage, or other persistence layer where you can securely save a player's LWA metadata
• The ability to securely and uniquely identify a player, i.e. by using a first-party account
• At least one Amazon account with an active Prime subscription for basic testing; the free trial works for this purpose if needed
• (recommended) Basic working knowledge of the OAuth 2.0 specification, especially Authorization Code Grants

Step-by-step instructions

The following is an overview of how to set up and use LWA for Devices in a Prime Gaming context. For more specific integration details, please refer to the official LWA for Devices docs.

1. Create a Security Profile and register your app with LWA. (main article: Register for Login with Amazon) For a basic LWA for Devices implementation, you'll only need a single Security Profile. Navigate to the "Device Settings" tab to register your app.
   • If this is your first time using the Developer Console, you'll need to set up an account; it's recommended to use a company-wide account instead of linking it to a particular person. Once created, you can add other users with specific permissions.
   • We recommend using a single Security Profile for all of your service's deployment environments (e.g. beta, staging, production). Login with Amazon only exposes its production environment, so additional profiles will all behave the same as the first.
2. Reach out to your Prime Gaming tech contact with your LWA client ID and Security Profile ID to be allow-listed for the games::prime scope. This OAuth scope authorizes your LWA client to retrieve a user's Prime Gaming entitlements, and is required. Please allow a short turnaround time for your LWA profile and client to be allow-listed.
3. Add a Login with Amazon button, menu option, or other element to your title. New users will interact with this element to start the account linking process.
   • Please connect with your Prime Gaming contact to ensure that the look and feel of this element is appropriate for your game while still meeting Amazon's style guidelines. For best practices and a list of available images, see the LWA Style Guidelines.
4. From your title, retrieve and display the user code and verification URL. (main articles: Retrieve Code and URL • Display Code and URL) Players will visit this URL on their smartphone or other device and enter the code.
   • The scope parameter of this request should be profile games::prime (profile%20games%3A%3Aprime when URL encoded). Note the space between the two scopes.
   • Once retrieved, the code and URL should be displayed in a static, dismissable screen or dialog that fits your game's look and feel.
5. While the code and URL are being displayed, periodically poll LWA's token endpoint. (main article: Retrieve an Access Token) The endpoint will update to include the access and refresh tokens when the user has finished entering the code.
   • Please ensure that you're not polling the token endpoint more often than specified by the interval value in the response that provided the user code and verification URL.
6. Use the access token to retrieve the customer's Amazon user_id. (main article: Obtain Customer Profile Information) The LWA documentation explains several approaches to this step in detail. Ultimately, the "account link" is the relationship between this ID and your game's player identifier (player ID, first-party account ID, etc.)
7. Securely store the Amazon ID and LWA tokens so they can be used to make Prime Gaming API calls on this user's behalf. Depending on your game's infrastructure, this may be communicated to a game server or stored on the client. This is discussed in more detail in the next section, Manage Linked Accounts.
8. Notify the user that account linking is complete. This message should include a call to action for the player to return to your title's Prime Gaming offer page and claim their offer.

Next: Manage Linked Accounts