Authorize Public Applications

Before your public application can call the Selling Partner API (SP-API) on behalf of a selling partner, the selling partner must grant permission to your application.

To grant permission, selling partners follow an authorization flow based on Login with Amazon (LWA), which is Amazon's implementation of OAuth 2.0. In the context of the SP-API, this authorization flow involves the following steps:

1. The selling partner grants your application permission by starting from either the Selling Partner Appstore or through an Authorize button on your website.
2. Amazon provides an authorization code that your application exchanges for refresh tokens.
3. During runtime, your application uses these tokens to make SP-API calls on behalf of the selling partner.

This topic provides an overview of the authorization methods for public applications and tips for when you implement authorization.

Authorization workflows

Depending on your implementation, selling partners can authorize your public application in two ways. Both workflows use OAuth 2.0 to ensure secure authorization, but they differ in where the selling partner starts the process:

• Selling Partner Appstore authorization workflow: In this workflow, selling partners find your application in the Selling Partner Appstore and choose Authorize Now from your application's detail page. For details, refer to Selling Partner Appstore Authorization Workflow.

• Website authorization workflow: In this workflow, selling partners visit your website and authorize your application through an Authorize button that you configure. For details, refer to Website Authorization Workflow.

For testing purposes, you can also self-authorize your public application through the private application authorization workflow.

About URIs in the authorization flow

OAuth authorization flows use the following URIs; each URI serves a specific purpose. For details about how to construct the URIs, refer to the documentation for the flow that you choose: the Selling Partner Appstore Authorization Workflow or the Website Authorization Workflow.

Log-in URI

• Who owns this endpoint: You.

• How you get this URI: You specify this URI as the OAuth Login URI when you register your application.

• How you use it: This URI is where selling partners log in to your website after they grant permission to your application. This log-in step lets you associate the authorized selling partner with their account in your system. After the selling partner logs in at the log-in URI, you redirect them to the Amazon callback URI.

• Required for: Both the website authorization flow and the Selling Partner Appstore authorization flow.

• Example: https://example.com/auth/login

Redirect URI

• Who owns this endpoint: You.

• How you get this URI: You specify this URI as the OAuth Redirect URI when you register your application. You can specify multiple redirect URIs.

• How you use it: Amazon redirects selling partners to this URI on your website after they complete the authorization process. You can include this URI as a parameter when you load the Amazon callback URI. Otherwise, Amazon uses the first redirect URI that you specified during registration.

• Required for: Both the website authorization flow and the Selling Partner Appstore authorization flow.

• Example: https://example.com/landing.html

Authorization URI

• Who owns this endpoint: Amazon.

• How you get this URI: You construct it by combining:

  • The Seller Central or Vendor Central URL for the specific marketplace
  • /apps/authorize/consent
  • Your application ID as a query parameter

• How you use it: You redirect selling partners to this URI to show them Amazon's consent page.

• Required for: The website authorization workflow and for testing the Selling Partner Appstore authorization workflow.

• Example: https://sellercentral.amazon.com/apps/authorize/consent?application_id=amzn1.sellerapps.app.12345-36a6-4942-a13e-EXAMPLEfcd28

Amazon callback URI

• Who owns this endpoint: Amazon.

• How you get this URI: You receive this URI as the amazon_callback_uri query parameter when Amazon calls your log-in URI.

• How you use it: You redirect selling partners to this URI so that they can continue Amazon's authorization workflow.

• Required for: The Selling Partner Appstore authorization workflow only. Not used in the website authorization workflow.

• Example: https://amazon.com/apps/authorize/confirm/amzn1.sellerapps.app.12345-67a-8bcd-b16c-474EXAMPLE57?redirect_uri=https://example.com/landing.html&amazon_state=amazonstateexample&state=-37131022

Authorization implementation tips

When you implement OAuth 2.0 authorization, consider the following aspects:

• Token handling

  • Authorization codes expire after five minutes, so exchange authorization codes for refresh tokens promptly.
  • Access tokens are short-lived (typically one hour).
  • Refresh tokens are long-lived. The selling partner must re-authorize your application (a process that generates a new refresh token) every 365 days. For details about the re-authorization process, refer to Renew Authorizations.
  • Use refresh tokens to get new access tokens during runtime.

• User consent

  • Request only the necessary permissions.
  • Explain why each permission is needed.

• Regional considerations

  • Use the correct regional endpoints.
  • Use the correct regional Seller Central URL or Vendor Central URL for both authorization URIs and selling partner interactions.