Onboarding Step 3: Authorize your Amazon Business API apps

Before you proceed in this section, make sure you've completed:

• Onboarding Step 1: Submit your developer profile request
• Onboarding Step 2: Create app client in Solution Provider Portal

Here, you'll learn how to (1) generate refresh token, (2) retrieve the access and refresh tokens, and (3) learn about authorization workflow.

A refresh and access token are required to access the Amazon Business APIs. Each regional Amazon Business marketplace has a unique token. If you have an Amazon Business account in multiple marketplace regions, generate a token for each region. For example, if you have Amazon Business accounts in Japan and the UK, you will need to generate one token for Japan and one for the UK. When generating a token, use the appropriate Amazon Business marketplace URL for your region. For more information, see Amazon Business store URLs.

Generate refresh token

1. In your browser, enter the Amazon Business marketplace URL for your region. For example, replace “amazon.com” in the following sample URL with “amazon.co.jp” for Japan or “amazon.de” for Germany. For a full list of regional URLs, see Amazon Business marketplace URLs.

https://www.amazon.com/b2b/abws/oauth?state=100&redirect_uri=

2. Add your redirect_uri and applicationId at the end of the Amazon Business URL. Use the same redirect_uri and applicationId you've provided in Solution Provider Portal (SPP). You'll encounter an error and be unable to proceed if there's a mismatch.

https://www.amazon.com/b2b/abws/oauth?state=100&redirect_uri=https://www.your_redirect_uri.com&applicationId=amzn1.sp.solution.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

The next screen prompts you to sign in.

🚧

If you are repeating the process, you will see the following screen. Select Remove access and proceed to Step 3.

3. Sign in using your Amazon Business admin account. This user account must be the admin for all legal entities under the Amazon Business account. The consent page displays upon successful sign-in.

🚧

Did you sign in with your Amazon Business account?

An error will occur if you're using a different Amazon account. If unsure, please sign out and sign back using your Amazon Business account.

5. Select Allow. The redirect URI displays.

The OAuth code is in the redirect URI. Make a note of this code.

🚧

Don't let the time run out.

The OAuth code is valid only for five minutes. If the five minutes lapsed, you'll need to repeat the process from steps 1-5.

Retrieve the access and refresh tokens

1. Use this CURL command to retrieve the access and refresh tokens.

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'

The LWA returns response in JSON format as shown here.

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"
}

The following are definitions for various parameters present in an LWA response. The response is in JSON and includes these elements.

Your app is now authorized to make calls to the Amazon Business API.

2. Save the refresh token to generate access tokens for subsequent API calls.

🚧

One hour validity

Access token is valid only for one hour. The LWA Authorization Server returns the LWA refresh token. Save the refresh token to generate access tokens for subsequent Amazon Business API calls. Use the same access token for multiple API calls until it expires.

Use this cURL command to retrieve the access token from the refresh token.

curl -k -X POST -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=refresh_token&refresh_token=refreshtoken_generated_from_step1&client_id=clientid_from_developer_ profile&client_secret=secret_from_developer_profile' 'https://api.amazon.com/auth/O2/token'

The LWA returns response in JSON format as shown here.

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"
}

Authorization Workflow

If you're a public developer interested in developing applications for business customers, you need to add authorization workflow. Adding authorization workflow allows your customers to successfully grant consent to your app. There are two authorization workflow options for you.

Authorization workflow options

Amazon Business App Center authorization workflow
This workflow requires you to create a listing request for Amazon Business App Center through SPP. If you opted for this option, complete the integration by following these steps.

Your website-based authorization workflow
This workflow requires you to create a UI-based authorization workflow on your website. If you opted for this option, complete your integration by following these steps.

Sample use cases

Use case 1. You have a single app that is available in Amazon Business US and Germany. You want to give consent to both.

In this case, you'll need to generate one token for Amazon Business US and and one token for Amazon Business Germany.

Generate a token for Amazon Business US.

1. Open your browser.
2. Copy and paste this URL, https://www.amazon.co.us/b2b/abws/oauth?state=100&redirect_uri=.
3. Add your redirect_uri and applicationId at the end of URL.

After adding your redirect_uri and applicationID at the end of the URL, the link will look like this, https://www.amazon.us/b2b/abws/oauth?state=100&redirect_uri=https://www.sample_redirect_uri.us&applicationId=amzn1.sp.solution.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

The next screen prompts you to sign in.

4. Sign in using your Amazon Business admin account. The consent page displays.
5. Select Allow. The next screen displays the redirect URI The OAuth code is in the redirect URI. Make a note of this code.

Sample redirect URI with OAuth code: https://www.sample_redirect_uri.us?state=100&code=SampleOAuth123.

6. Log out from your Amazon Business admin account.

Generate a token for Amazon Business Germany.

1. Open your browser.
2. Copy and paste this URL, https://www.amazon.co.de/b2b/abws/oauth?state=100&redirect_uri=.
3. Add your redirect_uri and applicationId at the end of URL.

After adding your redirect_uri and applicationID at the end of the URL, the link will look like this, https://www.amazon.co.de/b2b/abws/oauth?state=100&redirect_uri=https://www.sample_redirect_uri.co.de&applicationId=amzn1.sp.solution.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

The next screen prompts you to sign in.

4. Sign in using your Amazon Business admin account. The consent page displays.
5. Select Allow. The next screen displays the redirect URI. The OAuth code is in the redirect URI. Make a note of this code.

Sample redirect URI with OAuth code: https://www.sample_redirect_uri.co.de?state=100&code=SampleOAuth123.

6. Log out from your Amazon Business admin account.

Use case 2. You’re using one account to log into multiple Amazon Business marketplaces (ES, UK, FR, DE, and IT) in EU region.

In this case, you’ll need to generate one token to give consent to all marketplaces in EU region.

Use case 3. You have accounts in multiple Amazon Business marketplaces but in different region.

In this case, you’ll need to generate a token for each Amazon Business marketplace in different region. Here’s a sample schema.

Frequently asked questions

Q: What happens if I’m not an admin of all legal entities in Amazon Business while performing authorization activity?

A: You’ll receive this error and will be unable to proceed.

To resolve this error, do these steps:

1. Ask your Amazon Business account admin to add you as an admin to all legal entities on Amazon Business account.
2. In your browser, enter the URL you created in Step 1 to generate a refresh token. The Remove previous access screen displays.

Sample URL for Amazon Business:
https://www.amazon.com/b2b/abws/oauth?state=100&redirect_uri=https://www.your_redirect_uri.com&applicationId=amzn1.sp.solution.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

3. Select Remove access. The consent page displays.

3. Select Allow. A success message displays.

The OAuth code is in the redirect URI.

Q: Can I provide consent if I don't have an admin account or not added as an admin at a legal entity level?

A: No. You must sign in using an admin account to provide consent. An error will occur if you aren't using an admin account while providing consent. To resolve the error, follow these steps.

Q: I'm getting an error that says "We're sorry. We can't connect this account." What's the cause of this error?

This error is caused by invalid redirect_uri and applicationId. You must use the same redirect_uri and applicationId you've provided in SPP. Any missing or additional characters will cause an error.

To resolve the error, follow these steps.

Q: What could cause an error while trying to generate an OAuth code?

A: An error occurs because of an invalid redirect_uri and applicationId. Use the same redirect_uri and applicationId you've provided in SPP. You'll encounter an error and unable to proceed if there's a mismatch.

To verify if you've provided a valid redirect_uri and applicationId, do these steps:

1. Sign in to SPP. The App ID column displays your applicationId.

2. To view your redirect_uri, select Edit App in Action column. This displays the app registration. Your redirect_uri is provided here.

Q: Does the refresh token expire?

A: No. Refresh token doesn’t expire, but it won't work if the authorization is revoked.