Seller Management

These endpoints manage Amazon seller connections and access tokens.

Claim Code

Claims an OAuth authorization code and creates seller credentials.

POST /api/claim-code

Authentication

Requires x-adb-access-token header with a valid ADB access token.

Request Body

{
  "seller_id": "string",
  "name": "string",
  "callback_url": "string",
  "code": "string"
}

Field	Type	Required	Description
`seller_id`	string	Yes	Data Border seller ID from OAuth redirect
`name`	string	Yes	Display name for the seller
`callback_url`	string	Yes	URL for future callbacks/webhooks
`code`	string	Yes	Claim code from OAuth redirect (expires in 5 minutes)

Response

{
  "success": true,
  "data": {
    "refresh_token": "srt_abc123def456..."
  }
}

Field	Description
`refresh_token`	Long-lived token for obtaining seller access tokens

Example

curl -X POST https://adb.example.com/api/claim-code \
  -H "Content-Type: application/json" \
  -H "x-adb-access-token: YOUR_ADB_ACCESS_TOKEN" \
  -d '{
    "seller_id": "seller_abc123",
    "name": "Acme Corp Amazon Store",
    "callback_url": "https://my-wms.com/webhooks/amazon",
    "code": "temp_claim_code_xyz"
  }'

Errors

Status	Message	Cause
400	`seller_id is required`	Missing seller ID
400	`code is required`	Missing claim code
401	`Invalid ADB access token`	Token invalid or expired
404	`Seller not found`	Seller ID doesn't exist
400	`Invalid or expired claim code`	Code expired (>5 min) or already used

Timing matters. The claim code expires 5 minutes after OAuth completion. Claim it immediately in your callback handler.

Get Seller Access Token

Exchanges a seller refresh token for a seller access token.

POST /api/get-seller-access-token

Authentication

Requires x-adb-access-token header with a valid ADB access token.

Request Body

{
  "seller_id": "string",
  "refresh_token": "string"
}

Field	Type	Required	Description
`seller_id`	string	Yes	The seller's unique identifier
`refresh_token`	string	Yes	The seller's refresh token

Response

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs..."
  }
}

Field	Description
`access_token`	JWT access token valid for 24 hours

Token Claims

The seller access token contains:

{
  "tenant_id": "clx1y2z3a4b5c6d7e8f9g0h1",
  "seller_id": "seller_abc123",
  "iat": 1640995200,
  "exp": 1641081600
}

Example

curl -X POST https://adb.example.com/api/get-seller-access-token \
  -H "Content-Type: application/json" \
  -H "x-adb-access-token: YOUR_ADB_ACCESS_TOKEN" \
  -d '{
    "seller_id": "seller_abc123",
    "refresh_token": "srt_abc123def456..."
  }'

Errors

Status	Message	Cause
400	`seller_id is required`	Missing seller ID
400	`refresh_token is required`	Missing refresh token
401	`Invalid ADB access token`	Token invalid or expired
404	`Seller not found`	Seller doesn't exist or belongs to different tenant
401	`Invalid refresh token`	Refresh token doesn't match

Create Sandbox Seller

Creates a seller with manually provided Amazon tokens for sandbox testing.

POST /api/create-sandbox-seller-with-tokens

Sandbox only. This endpoint is only available when IS_SANDBOX=yes is set on the Data Border instance.

Authentication

Requires x-adb-access-token header with a valid ADB access token.

Request Body

{
  "seller_name": "string",
  "marketplace_region": "string",
  "amazonTokenSecret": "string",
  "sandbox_refresh_token": "string"
}

Field	Type	Required	Description
`seller_name`	string	Yes	Display name for the seller
`marketplace_region`	string	Yes	`us-east-1`, `eu-west-1`, or `us-west-2`
`amazonTokenSecret`	string	Yes	Base64-encoded encryption key (min 32 bytes decoded)
`sandbox_refresh_token`	string	Yes	Amazon refresh token from Solutions Provider Portal

Response

{
  "success": true,
  "data": {
    "seller_id": "seller_abc123",
    "seller_name": "Test Sandbox Seller",
    "marketplace_region": "us-east-1"
  }
}

Example

# Generate a secure token secret
SECRET=$(openssl rand -base64 32)

curl -X POST https://adb.example.com/api/create-sandbox-seller-with-tokens \
  -H "Content-Type: application/json" \
  -H "x-adb-access-token: YOUR_ADB_ACCESS_TOKEN" \
  -d '{
    "seller_name": "Test Sandbox Seller",
    "marketplace_region": "us-east-1",
    "amazonTokenSecret": "'$SECRET'",
    "sandbox_refresh_token": "Atzr|IwEBIK1..."
  }'

Errors

Status	Message	Cause
403	`This endpoint is only available in sandbox mode`	`IS_SANDBOX` not set
400	`amazonTokenSecret must be a valid base64 encoded string`	Invalid base64
400	`amazonTokenSecret must be at least 32 bytes when base64 decoded`	Secret too short

Token Comparison

Token Type	Validity	Refresh	Used With Header
Seller Refresh Token	Never expires	N/A	N/A (used to get access token)
Seller Access Token	24 hours	Via refresh token	`x-seller-access-token`
Amazon Token Secret	N/A (encryption key)	N/A	`x-amazon-token-secret`

Common Usage Pattern

// Token manager example
class SellerTokenManager {
  async getSellerCredentials(sellerId) {
    // Check cache first
    let token = this.cache.get(`seller:${sellerId}:accessToken`)
    
    if (!token || this.isExpiringSoon(token)) {
      // Refresh the token
      const seller = await this.db.getSeller(sellerId)
      const adbToken = await this.getAdbAccessToken()
      
      const response = await fetch('/api/get-seller-access-token', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'x-adb-access-token': adbToken
        },
        body: JSON.stringify({
          seller_id: sellerId,
          refresh_token: seller.refreshToken
        })
      })
      
      const data = await response.json()
      token = data.data.access_token
      
      // Cache for ~23 hours
      this.cache.set(`seller:${sellerId}:accessToken`, token, 23 * 60 * 60)
    }
    
    // Return both credentials needed for API calls
    return {
      accessToken: token,
      amazonTokenSecret: await this.db.getSellerSecret(sellerId)
    }
  }
}

Next Steps

OAuth Flow

Understand the Amazon authorization process.

PII Access

Access customer data through the PII API.