Third-party website authorization workflow

The Website authorization workflow is an OAuth authorization workflow that is initiated from your own website. Amazon Business customer signs into your website and selects the “Authorize” button. This initiates the authorization. For more information, see Step 0. Set up an "Authorize" button.

Testing your authorization workflow

Before creating a production Website authorization workflow, test your authorization workflow while your application is in draft status. By testing, you can ensure that your application can exchange parameters with Amazon Business 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, construct one or more OAuth authorization URIs.

You are now ready to test your authorization workflow with your own business account. Start at Step 1. Business customer initiates authorization from your website. When you have finished testing the authorization workflow you can convert it to a production workflow. Now, any business customer can authorize your published application starting at Step 1. Business customer 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 business customer can select to initiate authorization of your application. When the business customer selects the button, your website loads an OAuth authorization URI into the browser and the business customer is redirected to an Amazon sign-in page. After sign-in, a consent page appears, where a business customer can give your application consent to make calls to the Amazon Business API on their behalf. For information about constructing an OAuth authorization URI, see Onboarding Step 4: Authorizing Amazon Business API applications.

📘

If you have OAuth authorization URIs for more than one region, be sure to set up your “Authorize” button(s) so that business customers are redirected to the specific Amazon Business site. Setting up your “Authorize” button(s) is a one-time task.

Step 1. Business customer initiates authorization from your website

  1. Business customer signs into your website. If the business customer doesn't have an account, they need to complete your registration process.

  2. Business customer selects "Authorize" 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 business customer is directed to the button that corresponds to the region that they buy in.

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

ParameterDescription
redirect_uriA URI for redirecting the browser to your application. This is the OAuth Redirect URI that you specified when you created your application. If you don't include the redirect_uri parameter, the default is the first OAuth Redirect URI that you specified when you created your application.

Optional

state

A state value generated by your application. Your application uses this value to maintain state between this request and the response, helping to guard against cross-site request forgery attacks.

📘

Because OAuth information is passed via URL query parameters, we highly recommended that you 1. Ensure that the state token is short-lived and verifiably unique to your user, and 2. Set the Referrer-Policy: no-referrer HTTP header, which prevents leaking sensitive information to websites that your website links to.

For more information about cross-site request forgery and calculating a state parameter, see Cross-site Request Forgery in the Login With Amazon documentation.

Step 2. Business customer consents to authorize the application

  1. Business customer signs into Amazon Business site. The consent page appears. For more information, see Onboarding Step 4: Authorizing Amazon Business API applications.

  2. Business customer views the consent page, reviews the data access requested by your application, and then selects Confirm to continue. Business customer have an option to Cancel and 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 Business customer'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 created your application, adding these query parameters.
ParameterDescription
stateThe state value from Step 1. Business customer initiates authorization from your website.
codeThe Login with Amazon (LWA) authorization code that you exchange for an LWA refresh token. For more information, see Onboarding Step 4: Authorizing Amazon Business API applications .

📘

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

For example:

‘https://redirect_uri/?state=100&code=RHkOnQzgFyDEERMviepT’. This is your authorization code. 

  1. Your application validates the state value.

  2. Your website's landing page displays.

Step 4. Your application exchanges the LWA authorization code for a LWA refresh token

Retrieve access and refresh tokens by using this CURL command.

curl -k -X POST -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=authorization_code&code=code_obtained_after_providing_consent&client_id=clientid_from_developer_ profile&client_secret=secret_from_developer_profle&redirect_uri=redirect_url_from_developer_profile' 'https://api.amazon.com/auth/O2/token'

For more information, see the LWA documentation:

To exchange an LWA authorization code for an LWA refresh token

  1. Your application calls the 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:
ParameterDescription
grant_typeThe type of access grant requested. Must be authorization_code.
codeThe LWA authorization code that you received above.
redirect_uriThe redirect URI for your application.
client_idPart of your LWA credentials. To get this value, see Viewing your developer information.
client_secretPart of your LWA credentials. To get this value, see Viewing your developer information.

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
  1. The LWA Authorization Server returns the LWA refresh token. The response is in JSON and includes the following elements.
ParameterDescription
access_tokenA token that authorizes your application to take certain actions on behalf of a business customer. See Onboarding Step 5: Create and sign your request on how to use this token to make API calls.
token_typeThe type of token returned. Should be bearer.
expires_inThe number of seconds before the access token becomes invalid.
refresh_tokenA long-lived token that can be exchanged for a new access token.
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"
}
  1. Your application saves the refresh_token value.

  2. The browser displays a page to the business customer 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 Amazon Business API 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.