Overview

This document provides you, Amazon Business developer partners, an overview of the Amazon Business App Center authorization workflow. After reading this document, you’ll learn how Amazon Business App Center authorization workflow works and how to authorize your application (app).

Amazon Business App Center authorization workflow is an OAuth authorization workflow that Amazon Business customer initiates from the Amazon Business App Center detail page. When you list an app in Amazon Business App Center, Amazon Business customer can authorize your app by selecting Connect app in the app detail page.

When Amazon Business customer selects the Connect app button, your app loads an OAuth authorization URI. You’ll authorize and authenticate the customer. Amazon Business customer is then redirected to Amazon Business App Center consent page. Amazon Business customer can give your app consent to make calls to Amazon Business App Center on their behalf.

Prerequisites

Before you proceed, check if you have:

• a Solution Provider Portal (SPP) account
• created an app with an Amazon Business role in SPP
• provided valid OAuth Login and OAuth Redirect URIs in your app client
• app client listing (optional)

If you answer yes to all, skip this section. Proceed to How it works.

No SPP account, yet? Refer to Submit your Developer Profile Request for instructions. Select at least one Amazon Business API role when you create your developer profile. This allows you to create an app client listing with Amazon Business App Center.

If you have an SPP account, but no app created, see Create App Client in Solution Provider Portal for instructions.

Valid OAuth Login and Redirect URIs must be provided in your app client before developing your OAuth flow. The redirect URI is used to send the OAuth code to enable API authorization, and the login URI is used to define the landing page that the user is directed to after selecting “Connect app.” The OAuth flow development cannot be completed without defining these URIs.

How it works

1. While logged in to their Admin account, the Amazon Business customer selects Connect app in the app details page of the Amazon Business App Center.

2. Amazon Business App Center redirects the request to your app URI. As part of the request, Amazon Business App Center passes the query parameters to the redirect_uri you’ve shared in SPP.

amazon_callback_uri=http://development.amazon.com/b2b/abws/applicationdetails/amzn1.sp.solution.7e82ee20-2de9-498b-a755-060f7810e3c9
amazon_state=eyJ6aXAiOiJERUYiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.XjvEabMxBU1T9b2pLgE-h9-U1cDKIY7QSQUWIHdJCh4PQQd3PNM2p56jY7tN9RoqC3OcMQfXiJTObOekheJ_DA

3. You’ll validate the Amazon Business customer account by passing parameters to amazon_callback_uri with your application_id.

amazon_callback_uri: https://www.amazon.com/b2b/abws/applicationdetails/{your_applicationid}

state=134334
redirect_uri=https%3A%2F%2Fd1hez9upnw5hy6.cloudfront.net%2Fauth
status=authentication_successful
amazon_state=eyJ6aXAiOiJERUYiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.XjvEabMxBU1T9b2pLgE-h9-U1cDKIY7QSQUWIHdJCh4PQQd3PNM2p56jY7tN9RoqC3OcMQfXiJTObOekheJ_DA

4. Once the authentication is successful, Amazon Business App Center displays the consent page to Amazon Business customers. Amazon Business customer has an option to Allow or Cancel access.

4a. If the Amazon Business customer selects Allow, the request redirects to your app (redirect_uri) with auth_code. Proceed to Step 5.

4b. If the Amazon Business customer selects Cancel, the flow ends. This means the Amazon Business customer didn’t provide consent. Amazon Business App Center won’t send a notification to you. Amazon Business customer is redirected to the app detail page.

amazon_callback_uri=http%3A%2F%2Fdevelopment.amazon.com%2Fb2b%2Fabws%2Fapplicationdetails%2Famzn1.sp.solution.7e82ee20-2de9-498b-a755-060f7810e3c9

amazon_state=eyJ6aXAiOiJERUYiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.kymeXiUSPMW_fzkfpeUMMS6VDnwQxFy2j68UpaadCksC
state=134334
auth_code=ANpamqfHlPdwrZiEuSHu

5. You’ll retrieve the refreshToken and accessToken by calling LWA (Login with Amazon). Learn more about LWA.

6. You’ll redirect the request to Amazon Business App Center using amazon_callback_uri and pass the in-query parameter as auth_code_use_successful (for successful request) or auth_code_use_failure (for failed request).

amazon_callback_uri: https://www.amazon.com/b2b/abws/applicationdetails/{your_applicationid}

amazon_state=eyJ6aXAiOiJERUYiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.kymeXiUSPMW_fzkfpeUMMS6VDnwQxFy2j68UpaadCksC 
status=auth_code_use_successful

7. After successful authentication and authorization, the status in your app detail page shows as connected.

Test your authorization workflow

By testing your authorization workflow, your app can exchange parameters with Amazon Business App Center and receive authorization information. It’s best to test your authorization workflow while your app is in DRAFT status. When you’re done testing the authorization workflow, submit the app listing for vetting process. After the vetting process, Amazon Business App Center displays your app.

Sample snippets

const queryStringParams = (new URL(document.location)).searchParams;
const amazonCallbackUri = queryStringParams.get("amazon_callback_uri");
const amazonState = queryStringParams.get("amazon_state");

setTimeout(() => {
    const redirectUrl = amazonCallbackUri + "?" + "amazon_state=" + amazonState
        + "&status=auth_code_use_successful";
    window.location.href = redirectUrl;
}, timeToWaitInMillisBeforeRedirection)

Frequently asked questions

Q: What will be the customer experience if you don’t send status of auth_code usage to Amazon Business?
A: The customer will get a generic error message.

For example:
We are sorry. Some exception occurred. Please try again.

Q: Is there a time limit within which auth_code usage status has to be communicated to Amazon Business App Center?
A: Yes, there is a time limit. The auth_code expires five minutes after issuance. An access token expires one hour after issuance.

Q: What are the steps to test the app connection between my site and the Amazon Business App Center?
A: To test the app connection status, visit your app details page. Your app details page displays a connection button or a connected view.

Q: How will I know if a customer disconnects the app from the Amazon Business App Center? Will I receive a notification?
A: You’ll not get a notification if the Amazon Business customer revokes the consent.

Appendix

The table of query parameters below will help you understand who sends a query parameter for each step in the authorization workflow.