Selling Partner Appstore Authorization Workflow

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:

Step 1. Initiate authorization from the Selling Partner Appstore

1. Sign in to Seller Central and navigate to the Selling Partner Appstore.
2. Open the Detail page for your application.
3. Choose Authorize Now.

Step 2. Consent to authorize your application

1. Review and accept the data access requested by your application.

2. Choose Login to < your application name > now.

   Amazon loads your Login URI (which you provided at application registration) into the browser, adding the following query parameters:

   Parameter	Description
   amazon_callback_uri	A URI for redirecting the browser to Amazon.
   amazon_state	A state value generated by Amazon to guard against cross-site request forgery attacks.
   selling_partner_id	The identifier of the selling partner who is authorizing your application.

   📘

   Note

   If this a test workflow (started by navigating to your OAuth authorization URI) Amazon includes the version=beta parameter. If this is a production workflow (started from the Selling Partner Appstore), Amazon does not include the parameter.

   For example:

   HTTP

   https://d2yzyfnnpjylxu.cloudfront.net/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
   

Step 3. Sign in to your website

1. Sign in to your website. If you don't have an account, you must first complete the registration process.

2. Your application loads the Amazon callback URI (passed by Amazon in the previous step) in to the browser, adding the following parameters:

📘

Note

If you are testing your workflow, you must also include the version=beta parameter, which ensures that the workflow authorizes an application in Draft state. If you do not include the parameter, the workflow authorizes an application published on the Selling Partner Appstore.

For example:

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

Or

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

Step 4. Amazon sends you the authorization information

Seller Central displays a notification indicating that Amazon is authorizing you to access the data. While this page is displayed, the following actions take place:

1. Amazon loads your OAuth Redirect URI in to the browser, adding the following query parameters:

   Parameter	Description
   state	The state value that you passed in the previous step.
   selling_partner_id	The identifier of the selling partner who is authorizing your application.
   spapi_oauth_code	The Login with Amazon (LWA) authorization code that you exchange for an LWA refresh token. For more information, refer to Step 5. Your application exchanges the LWA authorization code for an LWA refresh token. Note: An LWA authorization code expires after five minutes. You must exchange it for an LWA refresh token before it expires.

   For example:

   HTTP

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

2. Your application validates the state value.

3. Your application saves the selling_partner_id and spapi_oauth_code values.

4. Your website's landing page launches.

🚧

Important

If the sign-up process takes longer than 10 minutes, the Amazon callback URI and state expires, breaking the workflow. If no redirect to Amazon’s callback URI is detected after sign-up, developers must 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.

Step 5. Exchange the LWA authorization code for an LWA refresh token

⭐

Tip

You can optionally use the Login with Amazon SDK for JavaScript to help with the exchange of an LWA authorization code for an LWA refresh token. For more information, refer to the Login with Amazon documentation:

• Add the Login with Amazon SDK for JavaScript

• Authorization Code Grant

1. Your application calls the Login with Amazon (LWA) authorization server (https://api.amazon.com/auth/o2/token) to exchange the LWA authorization code for an LWA refresh token. The call must include the following query parameters:

   Parameter	Description
   grant_type	The type of access grant requested. Must be authorization_code.
   code	The LWA authorization code that you received in Step 4. Amazon sends you the authorization information.
   redirect_uri	The redirect URI for your application.
   client_id	Part of your LWA credentials. To get this value, refer to Viewing your application information and credentials.
   client_secret	Part of your LWA credentials. To get this value, refer to Viewing your application information and credentials.

   For example:

   HTTP

   POST /auth/o2/token HTTP/l.l
   Host: api.amazon.com
   Content-Type: application/x-www-form-urlencoded;charset=UTF-8
   grant_type=authorization_code&code=SplxlOexamplebYS6WxSbIA&client_id=foodev&client_secret=Y76SDl2F
   

2. The LWA Authorization Server returns the LWA refresh token. The response is in JSON and includes the following elements:

   Parameter	Description
   access_token	A token that authorizes your application to take certain actions on behalf of a selling partner. For more information, refer to Connecting to the Selling Partner API.
   token_type	The type of token returned (should be bearer).
   expires_in	The number of seconds before the access token becomes invalid.
   refresh_token	A long-lived token that can be exchanged for a new access token. For more information, refer to Connecting to the Selling Partner API.

   HTTP

   HTTP/l.l 200 OK
   Content-Type: application/json;
   charset UTF-8
   Cache - Control: no-store
   Pragma: no-cache
   {
     "access_token": "Atza|IQEBLjAsAexampleHpi0U-Dme37rR6CuUpSR",
     "token_type": "bearer",
     "expires_in": 3600,
     "refresh_token": "Atzr|IQEBLzAtAhexamplewVz2Nn6f2y-tpJX2DeX"
   }
   

3. Your application saves the refresh_token value.

4. The browser opens a page that indicates next steps for using your application.

   📘

   Note

   An LWA refresh token is a long-lived token that you exchange for an LWA access token. An access token obtained through this token exchange must be included with calls to all Selling Partner API operations except restricted operations and grantless operations, which use somewhat different authorization models. After an access token is issued it is valid for one hour. The same access token can be used for multiple API calls, until it expires.

   To exchange a refresh token for an access token using a generated SDK, refer to Connecting to the Selling Partner API using a generated Java SDK. To manually exchange a refresh token for an access token, refer to Connecting to the Selling Partner API.

   🚧

   Important

   For hybrid Selling Partner API applications: If an MWS auth token was returned in Step 4. Amazon sends you the authorization information, your application is also authorized to make calls to Amazon Marketplace Web Service on the selling partner's behalf.

Step 6. (Optional) Test your authorization workflow

We recommend that you test your authorization workflow to ensure that your application can exchange parameters with Amazon and receive authorization information. You must test your authorization workflow while your application is in Draft status.

1. Ensure that your application is in Draft status.

2. Construct one or more OAuth authorization URIs for testing purposes. Include the version=beta parameter in the OAuth URI(s) to indicate that the workflow is for authorizing an application in Draft status. For more information, refer to Constructing an OAuth authorization URI.

   Instead of starting at Step 1. The selling partner initiates authorization from the Selling Partner Appstore., you can start the test workflow by navigating to an existing OAuth authorization URI.

   ⭐

   Tip

   If you are testing your workflow with a trusted selling partner, ensure that they have the OAuth authorization URI that corresponds to their operating region.

   If your test authorization workflow is successful, you can convert it to a production workflow.

Step 7. (Optional) Convert your test authorization workflow to a production workflow

1. List your application in the Selling Partner Appstore. This action automatically changes your application from Draft to Published.

2. Update your workflow to remove the version=beta parameter to the Amazon callback URI.Removing that parameter ensures that any selling partner can authorize your published application starting at Step 1.

Workflow diagram

The following diagram provides an overview of the Selling Partner Appstore and website OAuth workflows.