Token Types
Understanding the different authentication tokens in Data Border
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
}
}