Authorization Workflow

This document explains the Website Authorization Workflow for connecting seller accounts to your application using Amazon's SP-API. It is a simplified and easy-to-follow guide, presented in clear, step-by-step instructions.

What is Website Authorization Workflow?

The Website Authorization Workflow enables public applications to connect with Amazon seller accounts. Sellers authorize your app via Amazon's login page, and your app receives access tokens to interact with SP-API on their behalf.

Prerequisites

Amazon Developer Account

App Registration

Obtain the Client ID, Client Secret, and App ID

Define your OAuth Redirect URI

Application Scope

Define the SP-API permissions (scopes) your app requires:

Example: sellingpartnerapi::migration or sellingpartnerapi::notifications

Step-by-Step Guide

Step 1: Build the Authorization URL

To initiate the workflow, direct the seller to Amazon's authorization page. Construct the URL as follows:

Parameters:

application_id: Your application's ID (e.g., amzn1.sellerapps.app.123456)

state: A unique, random string to protect against CSRF attacks (e.g., secure_random_string)

redirect_uri: Your app's callback URI (e.g., https://yourapp.com/oauth/callback)

Example:

https://sellercentral.amazon.com/apps/authorize/consent
?application_id=amzn1.sellerapps.app.123456
&state=secure_random_string
&redirect_uri=https://zamorins-sp-api.com/oauth/callback

Step 2: Seller Logs In and Grants Permissions

The seller logs in to their Amazon account and reviews the permissions your app is requesting.

Upon granting access, Amazon redirects the seller to your redirect_uri with the following query parameters:

state: The same state string you sent (validate this)

code: The authorization code you'll use to get tokens

Example Redirect:

Step 3: Exchange Authorization Code for Tokens

Make a POST request to Amazon's OAuth token endpoint to exchange the code for an access token and refresh token.

Endpoint:

https://api.amazon.com/auth/o2/token

Request Parameters:

{
  "grant_type": "authorization_code",
  "code": "<AUTHORIZATION_CODE>",
  "redirect_uri": "<YOUR_REDIRECT_URI>",
  "client_id": "<CLIENT_ID>",
  "client_secret": "<CLIENT_SECRET>"
}

Example Code (Python):

Response Example:

{
  "access_token": "Atza|IwEBL0B1...",
  "refresh_token": "Atzr|IwEBL0B1...",
  "token_type": "bearer",
  "expires_in": 3600
}

Step 4: Use Access Token for API Requests

Use the access_token to make API requests to SP-API endpoints on behalf of the seller. Include the token in the Authorization header:

Example Request:

Step 5: Refresh Tokens When Expired

Access tokens are short-lived (typically 1 hour). Use the refresh_token to request a new access_token.

Request Parameters:

{
  "grant_type": "refresh_token",
  "refresh_token": "<REFRESH_TOKEN>",
  "client_id": "<CLIENT_ID>",
  "client_secret": "<CLIENT_SECRET>"
}

Example Code:

Best Practices

Store client_secret and refresh_token securely using tools like AWS Secrets Manager or encrypted databases

Ensure the state parameter in the redirect matches your original string

Implement retries for transient errors (e.g., 5xx responses)

Schedule token refreshes before access tokens expire

Gracefully handle scenarios where a seller revokes access

Common Errors

Error Code	Description	Solution
invalid_grant	Invalid or expired authorization code	Ensure the code is valid and hasn't expired
unauthorized_client	Client ID/Secret is invalid	Verify your app credentials
invalid_request	Incorrect request format	Check all required parameters

What is Website Authorization Workflow?#

Prerequisites#

Amazon Developer Account#

App Registration#

Application Scope#

Step-by-Step Guide#

Step 1: Build the Authorization URL#

Step 2: Seller Logs In and Grants Permissions#

Step 3: Exchange Authorization Code for Tokens#

Step 4: Use Access Token for API Requests#

Step 5: Refresh Tokens When Expired#

Best Practices#

Common Errors#