Third-party website authorization workflow
This document provides you, Amazon Business developer partners, an overview of the Amazon Business third-party website authorization workflow. After reading this document, you’ll learn how (1) Amazon Business third-party website authorization workflow works and (2) Amazon Business customer authorizes your website app.
Amazon Business third-party website authorization workflow is an OAuth authorization workflow that Amazon Business customer initiates from your website. Amazon Business customer signs into your website and selects the Authorize button. This initiates the authorization.
How it works
Step 0. Set up an Authorize button
You'll set up an Authorize button (or something similar) on your app website that the Amazon Business customer can select to initiate authorization of your app. When Amazon Business customer selects the button, your website loads an OAuth authorization URI into the browser. The Amazon Business customer is redirected to an Amazon Business sign-in page. After sign in, a consent page appears. Refer to Onboarding Step 3: Authorizing Amazon Business API apps.
Step 1. Amazon Business customer initiates authorization from your website
Step 1a. Amazon Business customer signs into your website.
If the Amazon Business customer doesn't have an account, ask the Amazon Business customer to complete the registration process.
Step 1b. Amazon Business customer selects the Authorize button.
If you have more than one regional Authorize button, ensure that the Amazon Business customer is directed to the button that corresponds to the region that they buy in.
Step 1c. The app loads the OAuth authorization URI into the browser and adds these query parameters.
| Parameter | Description |
|---|---|
redirect_uri | A URI for redirecting the browser to your app. This is the OAuth Redirect URI that you specified when you created your app. If you don't include the redirect_uri parameter, the default is the first OAuth redirect URI that you specified when you created your app. |
state | A state value generated by your app. Your app uses this value to maintain state between this request and the response, helping to guard against cross-site request forgery attacks. |
OAuth information is passed through URL query parameters. We recommend you to do these: (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 to prevent leaking sensitive information to websites that your website links to. Refer to Cross-site request forgery.
Step 2. Amazon Business customer consents to authorize the app
The Amazon Business customer signs into Amazon Business site. The consent page appears. The customer views the consent page, reviews the data access requested by your app, and selects Confirm to continue. The Amazon Business customer has an option to Cancel and exit without authorizing. Refer to Onboarding Step 4: Authorizing Amazon Business API applications.
Step 3. Amazon sends you the authorization information
Amazon Business briefly displays a page indicating that we are authorizing you to access the customer's data. While that page is displayed, these actions take place:
- Amazon Business loads your OAuth redirect URI into the browser with these query parameters.
| Parameter | Description |
|---|---|
state | The state value from Step 1. Business customer initiates authorization from your website. |
code | The Login with Amazon (LWA) authorization code that you exchange for an LWA refresh token. Refer to Onboarding Step 3: Authorizing Amazon Business API applications. The LWA authorization code expires after five minutes. Exchange it for an LWA refresh token before it expires. |
Example:
https://redirect_uri/?state=100&code=RHkOnQzgFyDEERMviepT. This is your authorization code.
- Your app validates the state value.
- Your website's landing page displays.
Step 4. Your app 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'
Exchange an LWA authorization code for an LWA refresh token
- Your app 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:
| Parameter | Description |
|---|---|
grant_type | The type of access grant requested. Must be authorization_code |
code | The LWA authorization code that you received. |
redirect_uri | The redirect URI for your app. |
client_id | Part of your LWA credentials.. |
client_secret | Part of your LWA credentials. |
To view your LWA credentials, refer to View your app information and credentials.
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 is in JSON and includes these elements.
| Parameter | Description |
|---|---|
access_token | A token that authorizes your app to take certain actions on behalf of a business customer. Refer to Onboarding Step 4: Create your request. |
token_type | The type of token returned. Should be a bearer. |
expires_in | The number of seconds before the access token becomes invalid. |
refresh_token | A 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"
}
- Your app saves the refresh_token value.
The 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 operation. 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.
- The browser displays a page to the business customer indicating the next steps.
Test your authorization workflow
Before creating a production Website authorization workflow, test your authorization workflow while your app is in draft status. By testing, you ensure that your app can exchange parameters with Amazon Business and receive authorization information. When you've finished testing the authorization workflow, convert your app to a production workflow.
References
Updated 6 months ago