Amazon SCPN authorization workflow

For seller applications only

The Amazon Seller Central Partner Network (Amazon SCPN) authorization workflow is an OAuth authorization workflow that the selling partner initiates from the Amazon SCPN detail page. When you list a Selling Partner API application on the Amazon SCPN, selling partners can authorize your application by clicking Authorize Now on the detail page.

Testing your authorization workflow

Before listing your application on the Amazon SCPN, you should test your authorization workflow while your application is in draft status. Your test workflow won’t be exactly the same as the final production workflow, but you'll be able to ensure that your application can exchange parameters with Amazon and receive authorization information.

To set up a test authorization workflow

1. Make sure 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, see Constructing an OAuth authorization URI.

3. At Step 3. The selling partner signs into your website, be sure that your workflow adds the version=beta parameter to the Amazon callback URI to indicate that the workflow is for authorizing an application in draft status.

You are now ready to test your authorization workflow with a trusted selling partner who works with you. Alternatively, you can test the workflow yourself, using your own selling account credentials. Instead of starting at Step 1. The selling partner initiates authorization from the Amazon Seller Central Partner Network, the selling partner starts the test workflow by navigating to an OAuth authorization URI that you constructed previously.

Note: If you have more than one regional OAuth authorization URI, be sure give the selling partner the OAuth authorization URI that corresponds to the region that they operate in.

When you have finished testing the authorization workflow you can convert it to a production workflow.

To convert your test authorization workflow to a productions workflow

1. List your application in the Amazon SCPN. This 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 in Step 3. The selling partner signs into your website.

   Now any selling partner can authorize your published application starting at Step 1. The selling partner initiates authorization from the Amazon Seller Central Partner Network.

Step 1. The selling partner initiates authorization from the Amazon SCPN.

1. The selling partner signs into Seller Central and goes to the Amazon Seller Central Partner Network (Amazon SCPN).

2. The selling partner goes to the detail page for your application and clicks Authorize Now. The consent page for your application appears.

Step 2. The selling partner consents to authorize your application

1. The selling partner views the consent page, reviews and accepts the data access requested by your application, and then clicks Login to [your application name] now to continue. The selling partner can click Cancel to exit without authorizing.

2. 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 (the selling partner started by navigating to your OAuth authorization URI) Amazon includes the version=beta parameter. If this is a production workflow (the selling partner started from the Amazon SCPN), 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

Your website's sign-in page appears.

Step 3. The selling partner signs into your website

1. The selling partner signs into your website. If the selling partner does not yet have an account, they complete your registration process.

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

Parameter	Description
redirect_uri	A 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_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 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, see Cross-site Request Forgery in the Login with Amazon documentation.

Note: If you include the version=beta parameter, the workflow authorizes an application in Draft state. If you do not include the parameter, the workflow authorizes an application published on the Amazon SCPN.

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 briefly displays a page indicating that Amazon is authorizing you to access the selling partner's data. While this page is displayed, the following actions take place:

1. Amazon loads your OAuth Redirect URI into the browser (the first one you specified when you registered you application ), 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.
mws_auth_token	The 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, see Hybrid Selling Partner API applications.
spapi_oauth_code	The Login with Amazon (LWA) authorization code that you exchange for an LWA refresh token. For more information, see Step 5. Your application exchanges the LWA authorization code for an LWA refresh token. Note: An LWA authorization code expires after five minutes. Be sure to 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

2. Your application validates the state value.

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

4. Your website's landing page displays.

Step 5. Your application exchanges the LWA authorization code for an LWA refresh token

The Login with Amazon SDK for JavaScript can help you with the exchange of an LWA authorization code for an LWA refresh token.

Note: An LWA authorization code expires after five minutes. Be sure to exchange it for an LWA refresh token before it expires.

For more information, see the Login with Amazon documentation:

• Add the Login with Amazon SDK for JavaScript (opens new window)

• Authorization Code Grant (opens new window)

To exchange an LWA authorization code for an LWA refresh token

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, see Viewing your application information and credentials.
client_secret	Part of your LWA credentials. To get this value, see 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.

Parameter	Description
access_token	A token that authorizes your application to take certain actions on behalf of a selling partner. See 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. See 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 displays a page to the selling partner that indicates next steps for using your application.

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, see Connecting to the Selling Partner API using a generated Java SDK. To manually exchange a refresh token for an access token, see Connecting to the Selling Partner API.

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, see Hybrid Selling Partner API applications.