Website Authorization Workflow
Authorize an app using a website.
The website authorization workflow (OAuth) is initiated from your own website. Selling partners sign in to your website and click 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 Constructing 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 click to initiate authorization for 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, the selling partner is redirected to a consent page where they can approve your application to make calls to the Selling Partner API on their behalf. For information about constructing an OAuth authorization URI, refer to Constructing 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.
Setting up Authorize buttons is a one-time task.
Step 2: Selling partner initiates authorization from your website
-
The selling partner signs in to your website. If the selling partner doesn't have an account, they must complete your registration process.
-
The selling partner clicks the Authorize button that you set up in Step 1.
-
Your application loads the OAuth authorization URI into the browser and adds the following query parameters:
ParameterDescription 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 recommended 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: 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
Constructing 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 click 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. While that page is displayed, the following actions take place:
-
Amazon loads your OAuth redirect URI into the browser and adds these query parameters:
Note
An LWA authorization code expires after five minutes. Be sure to generate an LWA refresh token before it expires.
Request 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 displays.
Step 5: Application uses LWA authorization code to generate 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
-
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:ParameterDescription 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 developer information. client_secret
Part of your LWA credentials. To get this value, refer to Viewing your developer information. Request 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 includes the following elements.
ParameterDescription access_token
A token that authorizes your application to take certain actions on behalf of a selling partner. Refer to Connecting to the SP-API for more information. 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. Refer to Connecting to the SP-API for more information. Response example:
{ "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 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 SP-API using a generated Java SDK. To manually use a refresh token to generate an access token, refer to Connecting to the SP-API.
For hybrid SP-API applications
If an MWS auth token is returned in Step 3, 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.
Important
For the Webstore authorization workflow to function, your application must be in published status.
-
Remove the
version=beta
parameter from the OAuth authorization URI.
Updated about 1 month ago