Integrate Directly with LWA
Important
The Buy with Prime API is offered as a preview and might change as we receive feedback and iterate on the interfaces. We are sharing this early documentation to help you learn about the Buy with Prime API as we write and iterate on the content.
If you prefer not to use the Buy with Prime UI library or a Login with Amazon (LWA) SDK to enable shoppers to log in with their Amazon account credentials, you can integrate directly with the LWA OAuth endpoint. This topic lists your LWA integration tasks if you choose this option.
Although direct LWA integration is the most flexible way to integrate with LWA, it has the following limitations:
- Direct LWA integration doesn't include Buy with Prime UI components; you must create your own components that follow the Buy with Prime UI guidelines. For pre-built UI components, integrate with LWA by using Buy with Prime UI library instead.
- For sign-in, direct LWA integration only supports redirection. If you want to have a pop-up window for sign-in, you must add that support yourself.
- Direct integration requires extra effort to clean up the shopper profile data when the shopper signs out.
If you don't want pre-built UI components but you want help building well-formed requests, you can integrate with LWA by using an LWA SDK.
Static versus dynamic redirection
Your integration tasks depend on whether you put the sign-in link on static URLs or dynamic URLs, so this topic contains a section for each type.
- 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 full authentication flow in each case, see LWA Authentication Flow.
Integration tasks if you use static redirection
The following table shows the back-end tasks to implement if you put the sign-in link on pages with static URLs.
| Task | Required? | Link to Details |
|---|---|---|
| Set up an LWA security profile and add the static URL as an Allowed Return URL in the security profile. | Yes | Set up an LWA security profile |
| Add a sign-in link to the page with the static URL. | Yes | Add a sign-in link |
| Generate and store a state. | Yes | Generate and store a state |
Call the LWA authorization endpoint with the static URL as the redirect_url query parameter. | Yes | Send an authorization request |
After LWA redirects the shopper back to the static URL (redirect_url), extract the authorization code, scope, and state from the query parameters and validate the state. | Yes | Extract information from the redirected URL |
| Call the LWA token endpoint to get an access token and refresh token. Extract the access token and refresh token from the response. Save the refresh token in the backend session data so that you can use it to request a new access token when the access token expires. | Yes | Send an access token request |
| Call the LWA customer profile endpoint to get shopper data. | No | Send a request for shopper data |
| Use the access token as the shopper identity token as an input parameter to Buy with Prime operations. | No | Create a delivery preview with the shopper's Amazon identity (as an example) |
| Use the LWA SDK to log the shopper out of LWA on your site, which clears the session tokens that LWA maintains. By design, the shopper isn't signed out of amazon.com. | Yes | Log Out Users in the LWA documentation. |
| After logging the shopper out of LWA, clean the state that you maintain for the shopper on your site. | Yes | On your site, delete the LWA access tokens associated with the shopper, and remove their profile information from your cache, local, or session storage. If your site doesn’t support account linking, delete the LWA refresh tokens associated with the shopper. |
Integration tasks if you use dynamic redirection
The following table shows the back-end tasks to implement if you put the sign-in link on pages with dynamic URLs.
| Task | Required? | Link to Details |
|---|---|---|
| Set up a redirect handler URL. | Yes | Set up a redirect handler URL |
| Set up an LWA security profile and add the redirect handler URL as an Allowed Return URL in the security profile. | Yes | Set up an LWA security profile |
| Add a sign-in link to the page with the dynamic URL. | Yes | Add a sign-in link |
| Generate and store a state. | Yes | Generate and store a state |
Have the sign-in link call the LWA authorization endpoint with the dynamic URL as the redirect_url query parameter. | Yes | Send an authorization request |
After LWA redirects the shopper back to the redirect handler URL (redirect_url), extract the authorization code, scope, and state from the query parameters and validate the state. | Yes | Extract information from the redirected URL |
| Call the LWA token endpoint to get an access token and refresh token. Extract the access token and refresh token from the response. Save the refresh token in the backend session data so that you can use it to request a new access token when the access token expires. | Yes | Send an access token request |
Redirect the shopper to the dynamic URL (the page the shopper was on when they clicked the sign-in link). You can find the dynamic URL from the state when you extract the state from the redirected URL. | Yes | Extract information from the redirected URL |
| Call the LWA customer profile endpoint to get shopper data. | No | Send a request for shopper data |
| Use the access token as the shopper identity token as an input parameter to Buy with Prime operations. | No | Create a delivery preview with the shopper's Amazon identity (as an example) |
| Use the LWA SDK to log the shopper out of LWA on your site, which clears the session tokens that LWA maintains. By design, the shopper isn't signed out of amazon.com. | Yes | Log Out Users in the LWA documentation. |
| After logging the shopper out of LWA, clean the state that you maintain for the shopper on your site. | Yes | On your site, delete the LWA access tokens associated with the shopper, and remove their profile information from your cache, local, or session storage. If your site doesn’t support account linking, delete the LWA refresh tokens associated with the shopper. |
Related topics
Updated 2 days ago