Manage and Sync Linked Accounts

Storing Account Links

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:

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

Syncing the Account Link State

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.

Create/Update Account Link

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:

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

Delete Account Link

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