Selling Partner Appstore authorization workflow

How to authorize an app using the Selling Partner Appstore.

Note: This authorization workflow is an OAuth authorization workflow for seller applications only.

Optional: Test your authorization workflow

We recommend that you test your authorization worklow 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.

Note: 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.

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 status to Published status.

  2. Update your workflow so that it no longer adds 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. The selling partner initiates authorization from the Selling Partner Appstore.

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:

ParameterDescription
amazon_callback_uriA URI for redirecting the browser to Amazon.
amazon_stateA state value generated by Amazon to guard against cross-site request forgery attacks.
selling_partner_idThe 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:

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 do not have an account, you must complete the registration process before you sign in.

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

ParameterDescription
redirect_uriA URI for redirecting the browser to your application. This must an OAuth Redirect URI that you specified when you registered your application. If you do not include the redirect_uri parameter, the default is the first OAuth Redirect URI that you specified when you registered your application.

Optional

amazon_stateThe amazon_state value passed by Amazon in the previous step.
state

A state value generated by your application. Your application uses this value to maintain state between this request and the response, helping to guard against cross-site request forgery attacks.

Important: Because OAuth information is passed via URI query parameters, we highly recommended that you do the following: (1) Ensure that the state token is short-lived and verifiably unique to your user, and (2) Set the Referrer-Policy: no-referrer HTTP header, which prevents leaking sensitive information to websites that your website links to. For more information about cross- site request forgery and calculating a state parameter, refer to Cross-site Request Forgery.

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:
ParameterDescription
stateThe state value that you passed in the previous step.
selling_partner_idThe identifier of the selling partner who is authorizing your application.
mws_auth_tokenThe MWSAuthToken value that you use when you create a query string for a call to Amazon Marketplace Web Service. The mws\_auth\_token parameter is only passed when the selling partner is authorizing a hybrid Selling Partner API (SP-API) application. Note that if you are the selling partner authorizing the hybrid SP-API application and the application owner (meaning you self-authorized your own Amazon MWS application) you will not receive the MWSAuthToken. For more information, refer to Hybrid Selling Partner API applications.
spapi_oauth_codeThe 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:

https://client-example.com?state=state-example&mws_auth_token=mwsauthtokenexample&selling_partner_id=sellingpartneridexample&spapi_oauth_code=spapioauthcodeexample
  1. Your application validates the state value.

  2. Your application saves the selling_partner_id, mws_auth_token (if passed), and spapi_oauth_code values.

  3. Your website's landing page launches.

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

Note: 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:

  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:
ParameterDescription
grant_typeThe type of access grant requested. Must be authorization_code.
codeThe LWA authorization code that you received in Step 4. Amazon sends you the authorization information.
redirect_uriThe redirect URI for your application.
client_idPart of your LWA credentials. To get this value, refer to Viewing your application information and credentials.
client_secretPart of your LWA credentials. To get this value, refer to Viewing your application information and credentials.

For example:

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
  1. The LWA Authorization Server returns the LWA refresh token. The response is in JSON and includes the following elements:
ParameterDescription
access_tokenA 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_typeThe type of token returned (should be bearer).
expires_inThe number of seconds before the access token becomes invalid.
refresh_tokenA long-lived token that can be exchanged for a new access token. For more information, refer to Connecting to the Selling Partner API.
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"
}
  1. Your application saves the refresh_token value.

  2. 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. For more information, refer to Hybrid Selling Partner API applications.

Step 6. Renew your authorization

  1. Sign in to Seller Central and navigate to the Manage your Apps page.
  2. Select Renew authorization to renew your authorization for 1 year.