Selling Partner OAuth 2.0 workflows: understand and optimize your OAuth integration

By Hina V., Sr Solutions Architect, Selling Partner Developer Services | August 23, 2023

Selling Partner OAuth 2.0 workflows provide secure and seamless authentication and authorization for Selling Partner API (SP-API) calls made by third-party apps or Selling Partner Appstore apps. OAuth workflows are an essential part of the SP-API ecosystem as they provide secure, designated access to Amazon Selling Partner account information. There are two ways to implement these workflows: 1) through the Selling Partner AppStore or 2) through developer integration with the developer website/application.

Selling Partner Appstore OAuth 2.0

Selling partners can use the Selling Partner Appstore to discover and connect with third-party applications that integrate with SP-API. Selling partners can use these applications to manage their Amazon selling business more efficiently. To use an application from the Selling Partner Appstore, the selling partner must authorize the application to access their Amazon Selling Partner account information. Application access is granted through an OAuth workflow that involves the following steps:

1. The selling partner initiates the authorization process by choosing the Authorize button or link on the application’s detail page. Amazon redirects the selling partner to the Seller/Vendor Central page to log in.
2. After logging in, the selling partner is asked to consent to the application accessing their Amazon Selling Partner account information.
3. Upon consent to authorize your application, Amazon directs the selling partner to the application’s OAuth Login URI. Here, the selling partner either signs in to their account on the developer’s platform, or they sign up in accordance with the developer’s requirements.
4. After signing in, the selling partner is directed to their Amazon selling page before Amazon appends the spapi_oauth_code and selling_partner_id to the application’s OAuth Redirect URI. Refer to Amazon sends you the authorization information for more information.
5. Developers should note that if the sign-up process takes longer than 10 minutes, the Amazon callback URI and state will expire, breaking the workflow. If no redirect to Amazon’s callback URI is detected after sign-up, developers should have the selling partner initiate the OAuth flow build using the website workflow. Alternatively, the selling partner can go back to the application’s Selling Partner Appstore detail page and restart the workflow.
6. Upon receiving the spapi_oauth_code, developers must use the Amazon LWA endpoint to exchange the spapi_oauth_code for a long term LWA refresh-token. Refer to Exchange the LWA authorization code for an LWA refresh token for more information.

Website OAuth 2.0 workflow

Developers can also implement Selling Partner OAuth 2.0 workflows by integrating directly with the Amazon website. The following directions assume that you have listed your application in the Selling Partner Appstore, which changes your application from draft status to published status. They also assume that the selling partner has completed the sign-up process on your platform to use your SP-API integration and that they have an active professional seller/vendor account on Amazon. Integrating directly with the Amazon website requires the following steps:

1. The developer sets up an Authorize button (or something similar) on the application website that the selling partner can choose to initiate authorization of your application. When the selling partner chooses the button, your website loads an OAuth authorization URI into the browser, and the selling partner is redirected to an Amazon sign-in page. Refer to The selling partner initiates authorization from your website for more information.
2. After signing in, a consent page appears where the selling partner can give your application consent to make calls to the Selling Partner API on their behalf. Developers should note that the selling partner can choose Cancel to exit without authorizing at this stage.
3. Upon confirmation, Amazon briefly displays a page indicating that they are authorizing your application to access the selling partner's data.
4. Amazon loads your OAuth Redirect URI into the browser, adding the spapi_oauth_code and selling_partner_id. Refer to Amazon sends you the authorization information.
5. Upon receiving the spapi_oauth_code, developers should use the Amazon LWA endpoint to exchange it for a long-term LWA refresh token. Refer to Exchange the LWA authorization code for an LWA refresh token for more information.

Note: Refer to the Website authorization workflow document for information on how to test the authorization workflow while your application is still in draft status.

The following diagram provides an overview of both OAuth Workflows.

In the Selling Partner OAuth 2.0 workflow there are some things to note that developers and selling partners should be aware of to ensure a seamless integration and user experience.

• Token Expiration and Refresh: OAuth code issued to third-party applications have a five-minute lifespan, after which they expire and become invalid. When this happens, the application must obtain a new code to continue making API calls on behalf of the selling partner. SP-API provides a long term LWA refresh token that can be used to obtain a new LWA access token without requiring the selling partner to re-authorize. Refer to Request a Login with Amazon access token for more information.

  The selling partner must re-authorize the application every 365 days. Selling partners can visit the Manage Your Apps page, where the selling partner can either extend expiry of the existing authorizations, where developer can continue to use the existing refresh-token, or they can select re-authorize and be directed to a consent page. Amazon then directs the selling partner to your application’s OAuth redirect URI, where developers must handle OAuth exchange and refresh properly to ensure the application continues to function as expected.

• User consent and permissions: The OAuth workflow is the mechanism for third-party applications to get access to Amazon Selling Partner account information. Selling partners must be informed of the permissions the application is requesting and must be given the option to grant or deny consent. Developers must ensure that their application requests only the permissions it needs to function, and they must provide clear and concise explanations of why each permission is necessary in the application detail page, as well as on their website marketing page. This helps avoid user confusion and distrust, and leads to a higher rate of consent.

• Endpoints: Seller Central provides different endpoints for each region (North America, Europe, and Japan) and marketplace. Developers should ensure their application uses the correct endpoint specific to the region and marketplace they are targeting to avoid unexpected behavior.

Conclusion

The website OAuth 2.0 workflow and the Selling Partner Appstore OAuth 2.0 workflow are both secure ways for websites and applications to access Amazon Seller Central account information. The developer should build against both workflows to best meet the needs of the selling partner.

👍

Have feedback on this post?

If you have questions or feedback on this post, we'd like to hear from you! Please vote and leave a comment using the tools at the bottom of this page.

Subscribe to updates via RSS feed.