Token Types
Data Border uses multiple token types for different purposes. Understanding each type helps you implement proper token management.
Token Overview
flowchart TD
subgraph Tenant["Tenant Level"]
A[Tenant Refresh Token] --> B[Data Border Access Token]
end
subgraph Seller["Seller Level"]
C[Seller Refresh Token] --> D[Seller Access Token]
end
subgraph Amazon["Amazon Level"]
E[Amazon Refresh Token] --> F[Amazon Access Token]
F --> G[RDT Token]
end
B --> C
D --> E Loading diagram...
Data Border Tenant Refresh Token
The root credential for your WMS tenant.
| Property | Value |
|---|---|
| Format | Random string (e.g., rt_abc123...) |
| Expiry | Never expires |
| Storage | Plain text in Data Border database |
| Purpose | Exchange for Data Border access tokens |
Obtaining
Returned when creating a tenant:
{
"success": true,
"data": {
"tenant_id": "clx1y2z3...",
"refresh_token": "rt_abc123..."
}
}
Usage
Exchange for a Data Border access token:
POST /api/get-adb-access-token
{
"tenant_id": "clx1y2z3...",
"refresh_token": "rt_abc123..."
}
Security
- Store encrypted at rest in your WMS
- Never expose to clients - server-side only
- Cannot be rotated without creating a new tenant
- One per tenant - shared across all operations
Data Border Access Token
Short-lived JWT for tenant-level operations.
| Property | Value |
|---|---|
| Format | JWT (HS256 signed) |
| Expiry | 30 days |
| Storage | Memory/cache |
| Purpose | Seller management operations |
Token Claims
{
"tenant_id": "clx1y2z3...",
"iat": 1640995200,
"exp": 1643587200
}
Usage
Use in x-adb-access-token header:
POST /api/claim-code
x-adb-access-token: eyJhbGciOiJIUzI1NiIs...
Refresh Strategy
// Refresh 7 days before expiry
const REFRESH_BUFFER = 7 * 24 * 60 * 60 * 1000
function shouldRefreshAdbToken(token) {
const decoded = decodeJwt(token)
const expiresAt = decoded.exp * 1000
return Date.now() > expiresAt - REFRESH_BUFFER
}
Data Border Seller Refresh Token
Credential for a connected Amazon seller.
| Property | Value |
|---|---|
| Format | Random string (e.g., srt_def456...) |
| Expiry | Never expires |
| Storage | Plain text in Data Border database |
| Purpose | Exchange for seller access tokens |
Obtaining
Returned when claiming OAuth authorization:
{
"success": true,
"data": {
"refresh_token": "srt_def456..."
}
}
Usage
Exchange for a seller access token:
POST /api/get-seller-access-token
x-adb-access-token: <ADB_TOKEN>
{
"seller_id": "seller_abc123",
"refresh_token": "srt_def456..."
}
Security
- Store encrypted per-seller in your WMS
- Pair with amazonTokenSecret - both needed for operations
- Cannot be rotated without re-OAuth
- One per seller per tenant
Seller Access Token
Short-lived JWT for seller operations.
| Property | Value |
|---|---|
| Format | JWT (HS256 signed) |
| Expiry | 24 hours |
| Storage | Memory/cache |
| Purpose | All seller API operations |
Token Claims
{
"tenant_id": "clx1y2z3...",
"seller_id": "seller_abc123",
"iat": 1640995200,
"exp": 1641081600
}
Usage
Use in x-seller-access-token header (with x-amazon-token-secret):
GET /api/pii/getPII/123-456
x-seller-access-token: eyJhbGciOiJIUzI1NiIs...
x-amazon-token-secret: BASE64_SECRET
Refresh Strategy
// Refresh 1 hour before expiry
const REFRESH_BUFFER = 60 * 60 * 1000
function shouldRefreshSellerToken(token) {
const decoded = decodeJwt(token)
const expiresAt = decoded.exp * 1000
return Date.now() > expiresAt - REFRESH_BUFFER
}
Amazon Refresh Token
Amazon's long-lived credential for SP-API access.
| Property | Value |
|---|---|
| Format | Amazon token string (e.g., Atzr|IwEB...) |
| Expiry | Never expires (until revoked) |
| Storage | AES-256-GCM encrypted in Data Border database |
| Purpose | Exchange for Amazon access tokens |
Encryption
Encrypted with the seller's amazonTokenSecret:
Plaintext: Atzr|IwEBIG...
Encrypted: BASE64(salt + iv + tag + ciphertext)
Security
- Never stored in plaintext - always encrypted
- Decryption requires amazonTokenSecret - which Data Border doesn't store
- Isolated per seller - unique encryption key each
- Revokable by Amazon or seller
Amazon Access Token
Short-lived token for SP-API requests.
| Property | Value |
|---|---|
| Format | Amazon token string |
| Expiry | ~1 hour |
| Storage | In-memory only |
| Purpose | Authenticate to Amazon SP-API |
Lifecycle
Data Border automatically manages Amazon access tokens:
sequenceDiagram
participant WMS
participant ADB
participant LWA as Amazon LWA
participant SPAPI as Amazon SP-API
WMS->>ADB: API request
ADB->>ADB: Decrypt Amazon refresh token
ADB->>LWA: POST /auth/o2/token
LWA->>ADB: Return access token (~1hr expiry)
ADB->>SPAPI: Use access token
SPAPI->>ADB: Response
ADB->>WMS: Return data Loading diagram...
Caching
Data Border caches Amazon access tokens until near expiry to minimize LWA calls.
Restricted Data Token (RDT)
Single-use token for accessing PII via SP-API.
| Property | Value |
|---|---|
| Format | Amazon RDT string |
| Expiry | Single use / ~1 hour |
| Storage | In-memory only |
| Purpose | Access restricted SP-API data (PII) |
Automatic Generation
Data Border automatically generates RDTs when accessing endpoints that require them:
sequenceDiagram
participant WMS
participant ADB
participant Amazon
WMS->>ADB: GET /passthrough-api/orders/.../buyerInfo
ADB->>ADB: Detect RDT requirement
ADB->>Amazon: POST /tokens/2021-03-01/restrictedDataToken
Amazon->>ADB: Return RDT
ADB->>Amazon: GET /orders/.../buyerInfo (with RDT)
Amazon->>ADB: Return buyer info
ADB->>WMS: Return data Loading diagram...
RDT Scope
Each RDT is scoped to specific data elements:
buyerInfo- Buyer name, emailshippingAddress- Shipping address detailsrestrictedReportDocument- Report content
Amazon Token Secret
Not a token, but the encryption key for Amazon tokens.
| Property | Value |
|---|---|
| Format | Base64-encoded random data |
| Length | 32-64 characters |
| Storage | Your WMS only - never stored in Data Border |
| Purpose | Encrypt/decrypt Amazon refresh token |
Critical Properties
The amazonTokenSecret is not stored in Data Border. You must store and provide it with every request that needs Amazon access.
- Generated during OAuth initialization
- Sent in
x-amazon-token-secretheader - Required for any operation accessing Amazon data
- If lost, seller must re-authorize
Token Comparison Table
| Token | Validity | Storage | Encrypted | Required For |
|---|---|---|---|---|
| Tenant Refresh | Forever | Data Border DB | No | Getting Data Border access tokens |
| Data Border Access | 30 days | Memory | No (JWT) | Seller management |
| Seller Refresh | Forever | Data Border DB | No | Getting seller access tokens |
| Seller Access | 24 hours | Memory | No (JWT) | All seller operations |
| Amazon Refresh | Forever | Data Border DB | Yes | Getting Amazon access |
| Amazon Access | ~1 hour | Memory | No | SP-API calls |
| RDT | Single use | Memory | No | PII access |
| Token Secret | N/A | Your WMS | N/A | Decrypting Amazon tokens |
Token Management Best Practices
Storage Recommendations
// Your WMS database schema
const sellerCredentials = {
// From Data Border
adbSellerId: 'seller_abc123',
sellerRefreshToken: encrypt('srt_def456...'), // Encrypt at rest
// Your secret
amazonTokenSecret: encrypt('BASE64_SECRET'), // Never send to Data Border for storage
// Cached tokens (optional, can regenerate)
cachedAccessToken: 'eyJ...',
accessTokenExpiry: new Date()
}
Refresh Patterns
class TokenManager {
constructor() {
this.tokens = new Map()
}
async getSellerToken(sellerId) {
const cached = this.tokens.get(sellerId)
// Refresh 1 hour before expiry
if (cached && cached.expiry > Date.now() + 3600000) {
return cached.token
}
const newToken = await this.refreshSellerToken(sellerId)
this.tokens.set(sellerId, {
token: newToken,
expiry: Date.now() + 24 * 3600000 // 24 hours
})
return newToken
}
}