Selling Partner Appstore Authorization Workflow

A selling partner can start the authorization process for your public application from two places:

• Your application's detail page in the Selling Partner Appstore (described in this topic).
• Your website (described in Website Authorization Workflow).

In the Selling Partner Appstore workflow, selling partners use the Selling Partner Appstore to find and authorize applications that help them manage their Amazon selling business. Before a selling partner can use your application, they must authorize it to access their account information through an OAuth workflow.

This topic includes:

• A step-by-step table showing the authorization workflow.
• Detailed information about the URIs, parameters, and tokens used in the workflow.

Selling Partner Appstore authorization workflow

The following overview diagram shows the authorization flow after the selling partner finds your app's detail page in the Selling Partner Appstore.

The following table describes the authorization process in more detail.

Authorization details

The following sections provide additional information about specific elements of the authorization process.

Website configuration details

Before you implement the authorization workflow, configure your website with the following security requirements:

• Set the following HTTP header to prevent cross-site request forgery:

  HTTP

  Referrer-Policy: no-referrer
  

• Create a dedicated redirect URI page (for example, https://www.example.com/sp-api/auth) that:

  • Receives authorization responses from Amazon.
  • Handles parameters securely.
  • Validates state parameters.
  • Follows your website's security best practices.

• If you support multiple regions, set up regional handling to ensure that:

  • Selling partners are directed to the correct regional Seller Central or Vendor Central URL.
  • Your redirect URI can process responses from all supported regions.

Important: Register your redirect URI when you register your application. Amazon will only send authorization responses to registered URIs. For details about redirect URIs, refer to Redirect URI details.

Log-in URI details

A log-in URI is an endpoint that you specify when you register your application. This URI is where Amazon sends the selling partner to log in to your website so that you can index the authorization to the correct selling partner in your own system.

When Amazon sends the request to your log-in URI, it includes the following parameters:

Example of a log-in URI:

https://example.com/index.html?amazon_callback_uri=https://amazon.com/apps/authorize/confirm/amzn1.sellerapps.app.2eca283f-9f5a-4d13-b16c-474EXAMPLE57&amazon_state=amazonstateexample&selling_partner_id=A3FHEXAMPLEYWS

Amazon callback URI details

The Amazon callback URI is where your website redirects the selling partner so that they continue the authorization workflow.

Your website receives the callback URI as the amazon_callback_uri query parameter when Amazon calls your log-in URI.

When your website redirects the selling partner to the callback URI, your website includes the following parameters:

For security, your application should:

• Generate a unique state token for each request to prevent cross-site request forgery (CSRF) attacks.
• Set the Referrer-Policy: no-referrer HTTP header.
• Validate the state parameter in the response.

Example of a production callback URI:

https://amazon.com/apps/authorize/confirm/amzn1.sellerapps.app.2eca283f-9f5a-4d13-b16c-474EXAMPLE57?redirect_uri=https://example.com/landing.html&amazon_state=amazonstateexample&state=-37131022

Example of a callback URI for authorizing an application that's in Draft state:

https://amazon.com/apps/authorize/confirm/amzn1.sellerapps.app.2eca283f-9f5a-4d13-b16c-474EXAMPLE57?redirect_uri=https://example.com/landing.html&amazon_state=amazonstateexample&state=-37131022&version=beta

Redirect URI details

A redirect URI is an endpoint that receives Amazon's authorization response after the selling partner grants permission.

When Amazon sends the request to your redirect URI, it includes the following parameters:

Example of a redirect URI:

https://client-example.com?state=state-example&selling_partner_id=sellingpartneridexample&spapi_oauth_code=spapioauthcodeexample

When your application receives this request, it should:

• Validate the state parameter to ensure that it matches the one you generated.
• Securely store the selling_partner_id if your application needs to track or manage selling partner-specific data.
• Promptly exchange the spapi_oauth_code for an LWA refresh token (within five minutes).

Important security considerations:

• The LWA authorization code (spapi_oauth_code) expires after five minutes. Exchange it for a refresh token before it expires.
• If the entire authorization process takes longer than 10 minutes, the workflow may break. In this case, the selling partner should restart the authorization process from the Selling Partner Appstore.

For more information on exchanging the authorization code for a refresh token, refer to Authorization code exchange details.

Authorization URI details

The authorization URI goes to a consent page within Seller Central or Vendor Central. Although selling partners normally authorize your application through the Selling Partner Appstore, you use the authorization URI to test your authorization workflow before you publish your application.

If you test with a selling partner, make sure to use the marketplace URL that matches their Seller Central or Vendor Central region.

To construct your Seller Central authorization URI for testing:

1. Start with the Seller Central URL for your target marketplace.

2. Find your application ID in Seller Central or the Solution Provider Portal.

3. Combine the Seller Central URL with /apps/authorize/consent?application_id={your application ID}.

4. If you want to test an application that is in the Draft state, add version=beta. (You can also test without version=beta; in that case, you are authorizing the published version of the application.)

   Example of a Seller Central authorization URI for testing a Draft application in the US marketplace:

   HTTP

   https://sellercentral.amazon.com/apps/authorize/consent?application_id=amzn1.sellerapps.app.0bf296b5-36a6-4942-a13e-EXAMPLEfcd28&version=beta
   

   Example of a Seller Central authorization URI for testing a Draft application in the Mexico marketplace:

   HTTP

   https://sellercentral.amazon.com.mx/apps/authorize/consent?application_id=amzn1.sellerapps.app.0bf296b5-36a6-4942-a13e- 
   EXAMPLEfcd28&version=beta
   

To construct your Vendor Central authorization URI for testing:

1. Start with the Vendor Central URL for your target marketplace.

2. Find your application ID in Vendor Central or the Solution Provider Portal.

3. Combine the Vendor Central URL with /apps/authorize/consent?application_id={your application ID}.

4. If you want to test an application that is in the Draft state, add version=beta. (You can also test without version=beta; in that case, you are authorizing the published version of the application.)

   Example of a Vendor Central authorization URI for testing a Draft application in the US marketplace:

   HTTP

   https://vendorcentral.amazon.com/apps/authorize/consent?application_id=amzn1.sellerapps.app.0bf296b5-36a6-4942-a13e- 
   EXAMPLEfcd28&version=beta
   

   Example of a Vendor Central authorization URI for testing a Draft application in the Mexico marketplace:

   HTTP

   https://vendorcentral.amazon.com.mx/apps/authorize/consent?application_id=amzn1.sellerapps.app.0bf296b5-36a6-4942-a13e-EXAMPLEfcd28&version=beta
   

State parameter details

Two different state parameters are used in the authorization flow to prevent cross-site request forgery attacks:

Your application should:

• Generate a unique state token for each authorization request.
• Store the state token securely until Amazon's response.
• Verify that the state in Amazon's response matches your stored value.
• Reject the authorization if the state doesn't match.

For more information about preventing cross-site request forgery attacks and generating secure state tokens, refer to Cross-site Request Forgery.

Token type details

A token is a secure digital key that represents authorization to access SP-API resources on behalf of a selling partner. There are two types of tokens:

• Access token: A short-lived credential that your application uses to make SP-API calls on behalf of a selling partner.
• Refresh token: A long-lived credential that your application uses to get new access tokens without requiring the selling partner to re-authorize.

Token storage details

When you store refresh tokens, follow these security best practices:

• Store tokens in a secure, encrypted database.
• Never store tokens in client-side code or logs.
• Never share or expose tokens in URLs.
• Implement secure backup and recovery procedures for your token database.
• Create an access control system that restricts token access to only the necessary parts of your application.
• Implement a process to handle token rotation and revocation.
• Track token age and prompt selling partners to reauthorize annually.

Authorization code exchange details

After receiving an authorization code ( spapi_oauth_code) from the redirect URI, your application exchanges the authorization code for tokens by sending a POST request to the Login with Amazon (LWA) authorization server (https://api.amazon.com/auth/o2/token) with the following parameters:

Example request to exchange an authorization code for tokens:

POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8

grant_type=authorization_code&code=SplxlOexamplebYS6WxSbIA&redirect_uri=https://example.com/redirect&client_id=foodev&client_secret=EXAMPLESECRET

The LWA server returns a JSON response with the following parameters:

Example response that contains the tokens:

{
  "access_token": "Atza|IQEBLjAsAexampleHpi0U-**************",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "Atzr|IQEBLzAtAhexamplewVz2Nn6f2y-tpJX2DeX"
}

Store the refresh token securely. For security best practices, refer to Token storage details.

Runtime token exchange details

During runtime, your application exchanges a refresh token for an access token, except in the case of grantless operations. Note that restricted data operations indirectly require an access token. (To get a restricted data token (RDT), you call the Tokens API with the access token; then you can call the restricted operation.)

To exchange a refresh token for an access token, your application sends a POST request.

Example request to exchange a refresh token for an access token:

POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8

grant_type=refresh_token&refresh_token=Atzr|IQEBLzAtAhexample&client_id=foodev&client_secret=EXAMPLESECRET

The LWA server returns a JSON response with the following parameters:

Example response that contains an access token:

{
  "access_token": "Atza|IQEBLjAsAexampleHpi0U-Dme37rR6CuUpSR",
  "token_type": "bearer",
  "expires_in": 3600
}

Use the returned access token in the authorization header of your SP-API requests. For more information about making SP-API calls, refer to Connect to the Selling Partner API.

You can also use an SDK to help you with this step. For details, refer to SP-API SDK.

Test your authorization workflow

Before you publish your application, test the authorization workflow to ensure that your application correctly exchanges parameters with Amazon.

To test your authorization workflow, take the following steps:

1. Verify that your application is in Draft state.

2. Construct the authorization URI. For details, refer to Authorization URI details. Because you're testing with a Draft application, include the version=beta parameter in the authorization URI. (If you test without version=beta, you are authorizing the published version of your application.)

3. Instead of having selling partners find your application in the Selling Partner Appstore, you can test by navigating directly to the authorization URI.

   If you test with a selling partner, make sure to use the marketplace URL that matches their Seller Central or Vendor Central region.

4. After successful testing, prepare for production:

   • List your application in the Selling Partner Appstore, which changes its state from Draft to Published.
   • Remove the version=beta parameter from your callback URI handling. This allows any selling partner to authorize your published application through the Selling Partner Appstore.