Website Authorization Workflow

The website authorization workflow (OAuth) is initiated from your own website. Selling partners sign in to your website and select an Authorize button that you configure to initiate authorization. For more information, refer to the following steps.

📘

Note

The examples in the following steps are for a seller application that uses 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, refer to Construct an OAuth authorization URI.

Before you create a production website authorization workflow, test your authorization workflow while your application is in DRAFT (version=beta) status. For more information, refer to Step 2. After you've verified that your workflow functions correctly, you can convert it from draft to production.

Step 1: Set up an Authorize button

Set up an Authorize button on your application website that the selling partner can select to initiate authorization for your application. When the selling partner selects the button, your website loads an OAuth authorization URI into the browser. Your website then redirects the selling partner to an Amazon sign-in page. After sign-in, your website redirects the selling partner to a consent page where they can approve your application to make calls to the Selling Partner API on their behalf. For more information, refer to Construct an OAuth authorization URI.

📘

Note

If you have OAuth authorization URIs for more than one region, make sure you set up your Authorize buttons accordingly. Selling partners need to be redirected to the Seller Central (for sellers) or Vendor Central (for vendors) sign-in page for their region.

Authorize button set up is a one-time task.

Step 2: The selling partner initiates authorization from your website

1. The selling partner signs in to your website. If the selling partner doesn't have an account, they must complete your registration process.

2. The selling partner selects the Authorize button that you set up in Step 1.

3. Your application loads the OAuth authorization URI into the browser and adds the following query parameters:

   Parameter	Description
   redirect_uri	(Optional) A URI that redirects the browser to your application. This must be the OAuth redirect URI that you specified when you registered your application. If you don't include the redirect_uri parameter, the default is the first OAuth redirect URI that you specified when you registered your application.
   state	A state value generated by your application. Your application uses this value to maintain state between this request and the response, which helps to guard against cross-site request forgery attacks.

🚧

Important

Because OAuth information is passed via URL query parameters, we recommend that you:

• Ensure that the state token is short-lived and verifiably unique to your user.
• Set the Referrer-Policy: no-referrer HTTP header, which prevents sensitive information leaking 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.

If you include the version=beta parameter, the workflow authorizes an application in DRAFT status. If you don't include this 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 3: The selling partner consents to application authorization

The selling partner signs in to Seller Central or Vendor Central, depending on the type of OAuth Authorization URI you constructed. For more information, refer to Construct an OAuth Authorization URI.

Upon sign-in, the consent page appears. The selling partner can now review the data access requested by your application. They can select Confirm to continue or Cancel to exit without authorizing.

Step 4: Amazon sends authorization information

Amazon briefly displays a page to indicate that we are authorizing you to access the selling partner's data. At the same time, the following actions take place:

1. Amazon loads your OAuth redirect URI into the browser and adds these query parameters:

   Parameter	Description
   state	The state value from Step 2.
   selling_partner_id	The identifier for the selling partner who is authorizing your application.
   spapi_oauth_code	The Login with Amazon (LWA) authorization code that you use to generate an LWA refresh token (refer to Step 5).

   📘

   Note

   An LWA authorization code expires after five minutes. Be sure to generate an LWA refresh token before it expires.

   Request example:

   HTTP

   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 displays.

Step 5: The application uses an LWA authorization code to generate an LWA refresh token

The Login with Amazon SDK for JavaScript can help you use an LWA authorization code to generate an LWA refresh token.

📘

Note

An LWA authorization code expires after five minutes. Make sure you use it to generate an LWA refresh token before it expires.

Use an LWA authorization code to generate an LWA refresh token

1. Your application calls the Login with Amazon (LWA) authorization server (https://api.amazon.com/auth/o2/token) to use the LWA authorization code to generate 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 View your Application Information and Credentials.
   client_secret	Part of your LWA credentials. To get this value, refer to View your Application Information and Credentials.

   Request example:

   HTTP

   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 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 used to generate a new access token. For more information, refer to Connecting to the Selling Partner API.

   Response example:

   JSON

   {
     "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 use to generate an LWA access token. An access token obtained through this token generation must be included with calls to all SP-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 use 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 use a refresh token to generate an access token, refer to Connecting to the Selling Partner API.

For hybrid SP-API applications

If an MWS auth token is returned in Step 4, your application is also authorized to make calls to Amazon MWS on the selling partner's behalf.

Convert test authorization workflow to production

There are two ways to convert from beta to production:

• List your application in the Selling Partner Appstore. This automatically changes your application status from DRAFT to PUBLISHED.

• Remove the version=beta parameter from the OAuth authorization URI.