Website Authorization Workflow

A selling partner can start the authorization process for your public application from two places:

• Your website (described in this topic).
• Your application's detail page in the Selling Partner Appstore (described in Selling Partner Appstore Authorization Workflow).

In the website workflow, selling partners visit your website and authorize your application through an Authorize button that you configure. Before a selling partner can use your application, they must authorize it to access their account information through an OAuth workflow.

This topic includes:

• A step-by-step table showing the authorization workflow.
• Detailed information about the URIs, parameters, and tokens used in the workflow.

Website authorization workflow

The following overview diagram shows the authorization flow when selling partners start from your website.

The following table describes the authorization process in more detail.

Authorization details

The following sections provide additional information about specific elements of the authorization process.

Website configuration details

Before you implement the authorization workflow, configure your website with the following security requirements:

• Set the following HTTP header to prevent cross-site request forgery:

  HTTP

  Referrer-Policy: no-referrer
  

• Create a dedicated redirect URI page (for example, https://www.example.com/sp-api/auth) that:

  • Receives authorization responses from Amazon.
  • Handles parameters securely.
  • Validates state parameters.
  • Follows your website's security best practices.

• If you support multiple regions, set up regional handling to ensure that:

  • Selling partners are directed to the correct regional Seller Central or Vendor Central URL.
  • Your redirect URI can process responses from all supported regions.

Important: Register your redirect URI when you register your application. Amazon will only send authorization responses to registered URIs. For details about redirect URIs, refer to Redirect URI details.

Authorization URI details

When selling partners choose your website's Authorize button, your application redirects them to the authorization URI, which goes to a consent page within Seller Central or Vendor Central.

To construct your authorization URI:

1. Start with the Seller Central URL or Vendor Central URL for your target marketplace.

2. Add /apps/authorize/consent.

3. Add your application ID as a query parameter (application_id={your application ID}).

4. Add a state parameter to help prevent cross-site request forgery attacks.

5. If you want to test an application that is in the Draft state, add version=beta. (You can also test without version=beta; in that case, you are authorizing the published version of your application.)

   Example of a production authorization URI:

   HTTP

   https://sellercentral.amazon.com/apps/authorize/consent?application_id=amzn1.sellerapps.app.2eca283f-9f5a-4d13-b16c-474EXAMPLE57&state=ourStateToken
   

   Example of a test authorization URI for an application that's in Draft state:

   https://sellercentral.amazon.com/apps/authorize/consent?application_id=amzn1.sellerapps.app.2eca283f-9f5a-4d13-b16c-474EXAMPLE57&state=ourStateToken&version=beta
   

Important security considerations:

• Use the marketplace URL that matches your selling partner's region
• Generate a unique state token for each authorization request
• Store the state token securely until Amazon's response

Log-in URI details

A log-in URI is an endpoint that you specify when you register your application. This URI is where Amazon sends the selling partner to log in to your website so that you can index the authorization to the correct selling partner in your own system.

When Amazon sends the request to your log-in URI, it includes the following parameters:

Example of a log-in URI:

https://example.com/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

Redirect URI details

A redirect URI is an endpoint that receives Amazon's authorization response after the selling partner grants permission in Seller Central or Vendor Central.

When Amazon sends the request to your redirect URI, it includes the following parameters:

Example of a redirect URI:

https://client-example.com?state=state-example&selling_partner_id=sellingpartneridexample&spapi_oauth_code=spapioauthcodeexample

When your application receives this request, it should:

• Validate the state parameter to ensure that it matches the one you generated
• Securely store the selling_partner_id if your application needs to track or manage selling partner-specific data
• Promptly exchange the spapi_oauth_code for an LWA refresh token (within five minutes)

Important security considerations:

• The LWA authorization code (spapi_oauth_code) expires after five minutes. Exchange it for a refresh token before it expires.
• If the entire authorization process takes longer than 10 minutes, the workflow may break. In this case, the selling partner should restart the process from your website.

For more information on exchanging the authorization code for a refresh token, refer to Authorization code exchange.

Amazon callback URI details

The Amazon callback URI is where your website redirects the selling partner so that they continue the authorization workflow.

Your website receives the callback URI as the amazon_callback_uri query parameter when Amazon calls your log-in URI.

When your website redirects the selling partner to the callback URI, your website includes the following parameters:

For security, your application should:

• Generate a unique state token for each request to prevent cross-site request forgery (CSRF) attacks.
• Set the Referrer-Policy: no-referrer HTTP header.
• Validate the state parameter in the response.

Example of a production callback URI:

https://amazon.com/apps/authorize/confirm/amzn1.sellerapps.app.2eca283f-9f5a-4d13-b16c-474EXAMPLE57?redirect_uri=https://example.com/landing.html&amazon_state=amazonstateexample&state=-37131022

Example of a callback URI for authorizing an application that's in Draft state:

https://amazon.com/apps/authorize/confirm/amzn1.sellerapps.app.2eca283f-9f5a-4d13-b16c-474EXAMPLE57?redirect_uri=https://example.com/landing.html&amazon_state=amazonstateexample&state=-37131022&version=beta

State parameter details

The state parameter is a security token that helps prevent cross-site request forgery attacks. Your application:

1. Generates this token and includes it in the authorization URI.
2. Receives it back from Amazon in the redirect URI.
3. Validates that the received value matches the generated value.

Your application should:

• Generate a unique state token for each authorization request
• Store the state token securely until Amazon's response
• Verify that the state in Amazon's response matches your stored value
• Reject the authorization if the state doesn't match

For more information about preventing cross-site request forgery attacks and generating secure state tokens, refer to Cross-site Request Forgery.

Authorization code exchange details

After receiving an authorization code ( spapi_oauth_code) from the redirect URI, your application exchanges the authorization code for tokens by sending a POST request to the Login with Amazon (LWA) authorization server (https://api.amazon.com/auth/o2/token) with the following parameters:

Example request to exchange an authorization code for tokens:

POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8

grant_type=authorization_code&code=SplxlOexamplebYS6WxSbIA&redirect_uri=https://example.com/redirect&client_id=foodev&client_secret=EXAMPLESECRET

The LWA server returns a JSON response with the following parameters:

Example response that contains the tokens:

{
  "access_token": "Atza|IQEBLjAsAexampleHpi0U-**************",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "Atzr|IQEBLzAtAhexamplewVz2Nn6f2y-tpJX2DeX"
}

Store the refresh token securely. For security best practices, refer to Token storage details.

Token type details

A token is a secure digital key that represents authorization to access SP-API resources on behalf of a selling partner. There are two types of tokens:

• Access token: A short-lived credential that your application uses to make SP-API calls on behalf of a selling partner.
• Refresh token: A long-lived credential that your application uses to get new access tokens without requiring the selling partner to re-authorize.

Token storage details

When you store refresh tokens, follow these security best practices:

• Store tokens in a secure, encrypted database.
• Never store tokens in client-side code or logs.
• Never share or expose tokens in URLs.
• Implement secure backup and recovery procedures for your token database.
• Create an access control system that restricts token access to only the necessary parts of your application.
• Implement a process to handle token rotation and revocation.
• Track token age and prompt selling partners to reauthorize annually.

Runtime token exchange details

During runtime, your application exchanges a refresh token for an access token, except in the case of grantless operations. Note that restricted data operations indirectly require an access token. (To get a restricted data token (RDT), you call the Tokens API with the access token; then you can call the restricted operation.)

To exchange a refresh token for an access token, your application sends a POST request.

Example request to exchange a refresh token for an access token:

POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8

grant_type=refresh_token&refresh_token=Atzr|IQEBLzAtAhexample&client_id=foodev&client_secret=EXAMPLESECRET

The LWA server returns a JSON response with the following parameters:

Example response that contains an access token:

{
  "access_token": "Atza|IQEBLjAsAexampleHpi0U-Dme37rR6CuUpSR",
  "token_type": "bearer",
  "expires_in": 3600
}

Use the returned access token in the authorization header of your SP-API requests. For more information about making SP-API calls, refer to Connect to the Selling Partner API.

You can also use an SDK to help you with this step. For details, refer to SP-API SDK.

Test your authorization workflow

Before you publish your application, test the authorization workflow to ensure that your application correctly exchanges parameters with Amazon.

To test your authorization workflow, take the following steps:

1. Verify that your application is in Draft state.

2. Because you're testing with a Draft application, include the version=beta parameter in the authorization URI. (If you test without version=beta, you are authorizing the published version of your application.)

   Example of an authorization URI for testing an application that's in Draft state:

   HTTP

   https://sellercentral.amazon.com/apps/authorize/consent?application_id=amzn1.sellerapps.app.2eca283f-9f5a-4d13-b16c-474EXAMPLE57&state=ourStateToken&version=beta
   

3. Test your website's Authorize button to ensure that it correctly constructs and uses the authorization URI.

   If you test with a selling partner, make sure to use the marketplace URL that matches their Seller Central or Vendor Central region.

4. After successful testing, prepare for production:

   • List your application in the Selling Partner Appstore, which changes its state from Draft to Published.
   • Remove the version=beta parameter from your authorization URI construction.