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
- Sign in to Seller Central and navigate to the Selling Partner Appstore.
- Open the Detail page for your application.
- Choose Authorize Now.
Step 2. Consent to authorize your application
-
Review and accept the data access requested by your application.
-
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:
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
-
Sign in to your website. If you don't have an account, you must first complete the registration process.
-
Your application loads the Amazon callback URI (passed by Amazon in the previous step) in to the browser, adding the following parameters:
Parameter | Description |
---|---|
redirect_uri | A 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_state | The 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 |
Note
If you are testing your workflow, you must also include the
version=beta
parameter, which ensures that the workflow authorizes an application inDraft
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:
-
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:
https://client-example.com?state=state-example&selling_partner_id=sellingpartneridexample&spapi_oauth_code=spapioauthcodeexample
-
Your application validates the state value.
-
Your application saves the
selling_partner_id
andspapi_oauth_code
values. -
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:
-
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:
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
-
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/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" }
-
Your application saves the
refresh_token
value. -
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.
-
Ensure that your application is in
Draft
status. -
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 inDraft
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
-
List your application in the Selling Partner Appstore. This action automatically changes your application from
Draft
toPublished
. -
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.
Updated 2 months ago