Permissions

This document explains how to manage and request permissions for accessing Amazon Seller data using the SP-API. It provides a step-by-step guide for understanding and handling permissions, so your app can interact with seller accounts on their behalf.

What are Permissions in SP-API?

Permissions in the context of Amazon SP-API define what data and actions your app can access for a seller account. When a seller connects your application to their account, they must grant specific permissions (scopes) that allow your app to perform actions like managing orders, retrieving inventory, and more.

Types of Permissions (Scopes)

Amazon uses scopes to determine the level of access your app has to a seller's account. Each scope grants your app specific API permissions. Below are some common scopes:

sellingpartnerapi::orders: Allows access to order-related data

sellingpartnerapi::inventory: Grants access to manage and retrieve inventory data

sellingpartnerapi::products: Allows access to product-related data

sellingpartnerapi::reports: Grants access to generate and retrieve reports

sellingpartnerapi::shipping: Allows access to manage shipping settings and fulfill orders

sellingpartnerapi::finance: Access to financial data like invoices and settlements

sellingpartnerapi::notifications: Allows your app to send notifications to the seller

Step-by-Step Guide to Handling Permissions

Step 1: Define Required Scopes for Your App

Before requesting permissions from a seller, determine what your app needs to access. Choose the appropriate scopes for your app based on its functionality. For example:

If your app manages orders and inventory, request sellingpartnerapi::orders and sellingpartnerapi::inventory

Example Scopes:

Step 2: Include Scopes in the Authorization URL

When you build the authorization URL to direct the seller to Amazon's login page, include the scope parameter, which specifies the permissions your app needs.

Authorization URL:

Parameters:

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

state: A unique, random string to protect against CSRF attacks

redirect_uri: Your app's callback URI

scope: A space-separated list of required permissions

Example URL:

Step 3: Seller Logs In and Grants Permissions

The seller will be redirected to the authorization page where they log in and grant your app the permissions you requested. They will see a list of scopes your app is requesting and have the option to approve or deny access.

Once the seller grants access, Amazon redirects them to your redirect_uri with the following parameters:

state: The same state string you sent

code: The authorization code to exchange for tokens

Example Redirect:

Step 4: Handle Permissions in the Access Token Response

When you exchange the authorization code for access and refresh tokens, the response will contain information about the granted permissions. This lets you confirm that your app has the correct scopes for accessing the seller's data.

Example Response:

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

The scope field in the response shows which permissions have been granted.

Step 5: Access Seller Data Based on Granted Permissions

Once you have the access token, you can start making SP-API requests. The seller's granted permissions will determine which endpoints you can access. For example:

Access Orders: Use the sellingpartnerapi::orders scope to call the orders API

Access Inventory: Use the sellingpartnerapi::inventory scope to retrieve inventory data

Example API Request (Orders):

Step 6: Handle Revoked Permissions

If the seller revokes your app's permissions (e.g., by disconnecting your app from their account), you will no longer be able to access the protected data. Your app should handle this scenario gracefully by checking the API's error responses and prompting the seller to reauthorize the app.

Example Error (Unauthorized):

{
  "errors": [
    {
      "message": "Unauthorized",
      "code": "Unauthorized",
      "details": "The access token has expired or been revoked."
    }
  ]
}

In such cases, prompt the seller to log in again and reauthorize the app.

Best Practices for Handling Permissions

Request Minimal Scopes

Only request the permissions your app needs

This improves security and reduces the risk of over-privileged access

Handle Permission Revocations

Detect and handle cases where a seller revokes your app's permissions

Check API responses and prompt the seller to reconnect when necessary

Secure Token Storage

Store tokens and secrets securely using AWS Secrets Manager or encrypted databases

Token Expiration Handling

Implement logic to refresh tokens when they expire or when permissions change

Common Errors

Error Code	Description	Solution
invalid_scope	The requested scope is invalid or not available	Check if the scope is correctly specified
access_denied	Seller denied access to requested permissions	Ensure the seller grants the required permissions
unauthorized	Access token has expired or been revoked	Refresh the token or prompt the seller to reauthorize

What are Permissions in SP-API?#

Types of Permissions (Scopes)#

Step-by-Step Guide to Handling Permissions#

Step 1: Define Required Scopes for Your App#

Step 2: Include Scopes in the Authorization URL#

Step 3: Seller Logs In and Grants Permissions#

Step 4: Handle Permissions in the Access Token Response#

Step 5: Access Seller Data Based on Granted Permissions#

Step 6: Handle Revoked Permissions#

Best Practices for Handling Permissions#

Request Minimal Scopes#

Handle Permission Revocations#

Secure Token Storage#

Token Expiration Handling#

Common Errors#