HomeDocumentationCode SamplesAnnouncementsModelsRelease NotesFAQGitHubVideos
Developer HubAPI StatusSupport
Documentation
Developer HubAPI StatusSupport

Selling Partner Appstore Authorization Workflow

Authorize an app using the Selling Partner Appstore.

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:

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

ParameterDescription
redirect_uriA URI for redirecting the browser to your application. This must be the 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.
    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&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:

  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
    
  2. 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"
    }
    
  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.

The Selling Partner OAuth 2.0 workflows diagram for seller, vendor, and developer integration.