LWA Authentication Flow
Buy with Prime API is now available for early access
Sign up for early access to the Buy with Prime API using the 'Sign Up' button below. The API may change as Amazon receives feedback and iterates on it.
To customize the Buy with Prime experience to shoppers on your site, you can enable shoppers to sign in (authenticate) using their Amazon account credentials. This topic describes the authentication flow if your site uses Login with Amazon (LWA) for authentication.
We describe the flow from two perspectives: the shopper's perspective and the back-end perspective. From the shopper's perspective, there is just one flow. For the back end, the flow depends on whether the web page the shopper starts from has a static URL or a dynamic URL:
- A static URL doesn't have any parameters. An example is
https://www.example.com/checkout. - A dynamic URL has parameters that change. For example, a product detail page might have a product ID in the URL (
https://www.example.com/product/red-shirt-1) and a cart page might have a cart ID in the URL (https://www.example.com/cart/cart-id).
For the back end, the URL type is important because after shoppers sign in, they expect to be redirected to the page they were on when they clicked the sign-in link.
Shopper sign-in flow
From a shopper's perspective, the sign-in experience has the following steps:
- The shopper clicks a sign-in link on your site.
- The shopper is redirected to a sign-in page.
- On the sign-in page, the shopper enters their Amazon account credentials.
- The shopper is redirected back to your site (the same page they were on when they clicked the sign-in link).
- The shopper continues their browsing or checkout experience on your site, although now the experience is more personalized. For example, delivery estimates might now automatically use the default shipping address from the shopper's Amazon account.
Back-end flow
As mentioned previously, the back-end flow depends on whether the shopper started on a page with a static URL or a dynamic URL. For details, see the following sections:
Authentication flow for static URLs
The following table shows the back-end flow when the shopper clicks a sign-in link from a static URL.
| Step | Actor | Action |
|---|---|---|
| 1 | Shopper | Visits a static URL on your site and clicks the sign-in link. |
| 2 | Your web server | Generates a state based on the current page’s static URL and anti-forgery key. Stores the state in the current session information. Also stores the anti-forgery key and the current page's URL in your back-end session database. |
| 3 | Your web server | Assembles query parameters for the upcoming call to the LWA authorization endpoint. The query parameters include the scope (requested permissions), the redirect_uri (set to the static URL) and the state that was calculated in the previous step. |
| 4 | Your web server | Calls the LWA authorization endpoint with the assembled query parameters. |
| 5 | LWA | Redirects the shopper to a page where they can sign in with their Amazon account credentials. |
| 6 | Shopper | Signs in. |
| 7 | LWA | Verifies the shopper's credentials. |
| 8 | LWA | Redirects the shopper back to the redirect_uri (the static URL) with the authorization code, scope, and state as query parameters. |
| 9 | Your web server | Extracts the authorization code, scope, and state from the URL. Also validates the state. |
| 10 | Your web server | Assembles query parameters for the upcoming call to the LWA token endpoint. The parameters include the authorization code, redirect_uri, and so on. Also includes code_verifier if the call to the authorization endpoint included a code_challenge parameter. |
| 11 | Your web server | Calls the LWA token endpoint. |
| 12 | LWA | Returns an access token and a refresh token. |
| 13 | Your web server | Stores the refresh token. To ensure continuous access throughout a session, links the refresh token with the current session in server-side session storage. |
| 14 | Your web server | (Optional) Calls the LWA customer profile endpoint with the access token to get shopper data. |
| 15 | Your web server | (Optional) Uses the access token as the shopper identity token as an input parameter to Buy with Prime operations. |
| 16 | Your web server | Personalizes the user interface based on steps 13 and/or 14. |
Authentication flow for dynamic URLs
The following table shows the back-end flow when the shopper clicks a sign-in link from a dynamic URL.
| Step | Actor | Action |
|---|---|---|
| 1 | Shopper | Visits a dynamic URL on your site and clicks the sign-in link. |
| 2 | Your web server | Generates a state based on the current page’s dynamic URL and anti-forgery key. Stores the state in the current session information. Also stores the anti-forgery key and the current page's URL in your back-end session database. |
| 3 | Your web server | Assembles query parameters for the upcoming call to the LWA authorization endpoint. The query parameters include the scope (requested permissions), the redirect_uri (set to the redirect handler page, not the dynamic URL) and the state that was calculated in the previous step. |
| 4 | Your web server | Calls the LWA authorization endpoint with the assembled query parameters. |
| 5 | LWA | Redirects the shopper to a page where they can sign in with their Amazon account credentials. |
| 6 | Shopper | Signs in. |
| 7 | LWA | Verifies the shopper's credentials. |
| 8 | LWA | Redirects the shopper to the redirect_uri (redirect handler URL) with the authorization code, scope, and state as query parameters. |
| 9 | Your web server | Extracts the code and state parameters from the URL, decodes the state to get the anti-forgery token and the destination URL, and validates that the values match the values that the web server stored when sending the authorization request. |
| 10 | Your web server | Assembles query parameters for the upcoming call to the LWA token endpoint. The parameters include the authorization code, redirect_uri, and so on. Also includes code_verifier if the call to the authorization endpoint included a code_challenge parameter. |
| 11 | Your web server | Calls the LWA token endpoint. |
| 12 | LWA | Returns an access token and a refresh token. |
| 13 | Your web server | Stores the refresh token. To ensure continuous access throughout a session, links the refresh token with the current session in server-side session storage. |
| 14 | Your web server | Redirects the shopper to the dynamic URL (for example, the product detail page). |
| 15 | Your web server | (Optional) Calls the LWA customer profile endpoint with the access token to get shopper data. |
| 16 | Your web server | (Optional) Uses the access token as the shopper identity token as an input parameter to Buy with Prime operations. |
| 17 | Your web server | Personalizes the user interface based on steps 19 and/or 20. |
Related topics
Updated 2 days ago