Website authorization workflow

The Website authorization workflow is an OAuth authorization workflow that is initiated from your own website. Selling partners sign into your website and click an “Authorize” button that you configure to initiate authorization. For more information, see Step 0. Set up an "Authorize" button.

Note. The examples in the following steps are for a seller application, using an OAuth authorization URI based on a Seller Central URL. For vendor applications, you can replace the Seller Central URL with a Vendor Central URL. For more information, see Constructing an OAuth authorization URI.

Testing your authorization workflow

Before creating a production Website authorization workflow, you should test your authorization workflow while your application is in draft status. By testing you can 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. At Step 0. Set up an "Authorize" button, when you construct one or more OAuth authorization URIs, add the version=beta parameter to the OAuth URI(s) 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. Start at Step 1. The selling partner initiates authorization from your website.

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 Selling Partner Appstore. This changes your application from draft status to published status.

   Important. Your application must be in published status for the Webstore authorization workflow to work.

2. Remove the version=beta parameter from the OAuth authorization URI(s) that you constructed in Step 0. Set up an "Authorize" button.

   Now any selling partner can authorize your published application starting at Step 1. The selling partner initiates authorization from your website.

Step 0. Set up an "Authorize" button

Set up an “Authorize” button (or something similar) on your application website that the selling partner can click to initiate authorization of your application. When the selling partner clicks the button, your website loads an OAuth authorization URI into the browser and the selling partner is redirected to an Amazon sign-in page. After sign-in, a consent page appears, where a selling partner can give your application consent to make calls to the Selling Partner API on their behalf. For information about constructing an OAuth authorization URI, see Constructing an OAuth authorization URI.

Note. If you have OAuth authorization URIs for more than one region, be sure to set up your “Authorize” buttons so that selling partners are redirected to the Seller Central (for sellers) or Vendor Central (for vendors) sign-in page for their own region.

Setting up your “Authorize” button(s) is a one-time task.

Step 1. The selling partner initiates authorization from 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. The selling partner clicks the "Authorize" button that you set up in Step 0. Set up an "Authorize" button. If you have more than one regional "Authorize" button, be sure that the selling partner is directed to the button that corresponds to the region that they sell in.

3. Your application loads the OAuth authorization URI into the browser, adding the following query parameters:

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 Selling Partner Appstore.

For example:

https://sellercentral.amazon.com/apps/authorize/consent?application_id=appidexample&state=stateexample&version=beta

OR

https://sellercentral.amazon.com/apps/authorize/consent?application_id=appidexample&state=stateexample

The selling partner arrives at the sign-in page of Seller Central (for sellers) or Vendor Central (for vendors).

Step 2. The selling partner consents to authorize the application

1. The selling partner signs into Seller Central or Vendor Central, depending on the type of OAuth Authorization URI you constructed. The consent page appears. For more information, see Constructing an OAuth Authorization URI.

2. The selling partner views the consent page, reviews the data access requested by your application, and then clicks Confirm to continue. The selling partner can click Cancel to exit without authorizing.

Step 3. Amazon sends you the authorization information

Amazon briefly displays a page indicating that we are authorizing you to access the selling partner's data. While that 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:

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 4. Your application exchanges the LWA authorization code for a 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

• Authorization Code Grant

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:

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.

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 3. Amazon sends you the authorization information, your application is also authorized to make calls to Amazon MWS on the selling partner's behalf. For more information, see Hybrid Selling Partner API applications.