Developer Console
Sign In
Sign In
Developer Console

Manage and Sync Linked Accounts

Overview
→
STEP 1:
Set Up LWA Account Linking
→
STEP 2:
Manage and Sync Linked Accounts
→
STEP 3:
Create a Fulfillment API

Your players' Amazon account ID and LWA metadata are sensitive information that you'll be using regularly over the course of your Prime Gaming campaign. It's important to store this data in a way that is secure, quick to retrieve, and ensures a unique relationship between an Amazon identity and a player identity.

When using LWA for Websites (or an LWA for Devices approach that communicates with a web service), the most common storage solution is to leverage your existing player account database. The specific approach will depend on your database configuration. For example, in a relational DBMS such as PostgreSQL or Amazon RDS, you might create a lookup table for the new data that is linked to your account table by a player ID. In a NoSQL system, you might append the new fields to your existing account records.

When using LWA for Devices purely on your game client, store each player's information however you would normally save sensitive data. Please consult with first-party documentation for more information if necessary.

The data you'll need to store for each account link includes:

  • The Amazon user_id (used to uniquely identify each linked Amazon identity; you should enforce uniqueness on this value)
  • The LWA access token (used as authorization for requests to Prime Gaming APIs)
  • The LWA refresh token (a much longer-lived value used as authorization when requesting a new access token)
  • A timestamp denoting when the LWA access token will expire (optional, but recommended; avoids HTTP 400 errors caused by expired tokens)

Here's an example schema for a lookup table in a relational DBMS:

Column Data Type Notes
player_id String The unique identifier for players in your account system.
amazon_id String The Amazon user_id; ex. amzn1.account.A1B2C3D4E5F6
access_token String
refresh_token String
access_token_expires Varies Examples include an epoch timestamp value (stored as an integer) or a DBMS-native timestamp. Calculated from the expires_in value in the LWA access token response.

Handling LWA Revocation

Customers can revoke your title's usage of their LWA account at any time from the Amazon account management page. If this happens, any attempt to use a refresh token to obtain a new access token will return an invalid_grant error. LWA will not provide any other proactive notification that this revocation has occurred. Please ensure that your services can gracefully handle this situation by clearing out any invalidated account links and updating website or game messages to reflect the unlinked state. Players should be able to re-link their Amazon account (or a different account) without any issues.

Unlinking an Account

You should also provide the ability for a customers to unlink their account—and potentially link a different account—on your end. Depending on your infrastructure and how you've set up account linking, this might include:

  • An account management web page that shows a player's current account links with options to remove an account or link a different account
  • Checking for an existing link on your LWA account linking page and providing unlink/relink options instead of redirecting to the login workflow
  • (LWA for Devices) A menu option in your game client to unlink a player's Amazon account

When Prime Gaming makes a request to your fulfillment API after a claim, our services need to include which game, studio, or publisher account should receive the content. The following APIs are used to sync the current state of your account links whenever one is created, updated, or deleted.

This POST request is used to report a new account link or update the metadata of an existing link.

  • Endpoint
    POST https://gaming.amazon.com/api/account/link
  • Header (required)
    Content-Type: application/json
    x-amz-access-token: This account link's customer's LWA access token
  • Data (JSON format)
    A requestInfo object with the following parameters:
Request Parameter Data Type Description
accountId String The game, studio, or publisher account ID used to identify this player in your systems. This ID will be sent with each request to your fulfillment API.
displayName String Optional. The player's username or other display name in your title. If provided, Prime Gaming can display this to customers on your campaign's offer page to confirm that the correct account is linked.
overwriteAllowed Boolean Optional; defaults to false. As a safety measure, this API will throw a 400 error by default if you try to update an account link that already exists. Set this parameter to true for requests that are true metadata updates (i.e. a new accountId or displayName).

An example of a well-formed request:

POST /api/account/link HTTP/1.1
Host: gaming.amazon.com
Date: Thu, 03 Jun 2022 12:00:00 GMT
Content-Type: application/json;charset UTF-8
x-amz-access-token: Atza|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR...
{
  "requestInfo": {
    "accountId": "player123",
    "displayName": "XxUs3rN4m3xX",
    "overwriteAllowed": false
  }
}
  • Returns
    HTTP 200: Success
    HTTP 400: An account link already exists for this Amazon user, but overwriteAllowed was not specified; no update was performed

This DELETE request should be used when a customer on your service chooses to unlink their accounts.

  • Endpoint
    DELETE https://gaming.amazon.com/api/account/link
  • Header (required)
    Content-Type: application/json
    x-amz-access-token: This account link's customer's LWA access token

An example of a well-formed request:

DELETE /api/account/link HTTP/1.1
Host: gaming.amazon.com
Date: Thu, 03 Jun 2022 12:00:00 GMT
Content-Type: application/json;charset UTF-8
x-amz-access-token: Atza|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR...
  • Returns
    HTTP 200: Success
    HTTP 400: No account link was found for this Amazon user

Other Considerations

  • If your title or account platform offers customers GDPR-compliant services such as permanently deleting or requesting a copy of their data, remember to include LWA and Prime Gaming claim data when doing so.

Next: Create a Fulfillment API