API Reference

This section provides complete documentation for all ShipStream Data Border API endpoints.

Base URL

All API endpoints are relative to your Data Border instance:

https://your-adb-instance.fly.dev

Authentication

Data Border uses multiple authentication methods depending on the endpoint:

Method	Header	Used For
JWT Bearer	`Authorization: Bearer <JWT>`	Tenant creation, Data Border access token
Data Border Access Token	`x-adb-access-token: <token>`	Seller management
Seller Access Token	`x-seller-access-token: <token>`	All seller operations
Amazon Token Secret	`x-amazon-token-secret: <secret>`	Decrypting Amazon tokens

API Groups

Tenant Management

Create tenants and manage Data Border access tokens.

Endpoint	Method	Description
`/api/create-tenant`	POST	Register a new WMS tenant
`/api/get-adb-access-token`	POST	Exchange refresh token for access token

Seller Management

Connect Amazon sellers and manage their access.

Endpoint	Method	Description
`/api/claim-code`	POST	Claim OAuth authorization code
`/api/get-seller-access-token`	POST	Get seller access token
`/api/create-sandbox-seller-with-tokens`	POST	Create sandbox seller (testing only)

OAuth

Amazon OAuth integration for seller authorization.

Endpoint	Method	Description
`/auth/initialize`	GET	Start OAuth flow
`/auth/redirect`	GET	OAuth callback handler

PII Access

Controlled access to personally identifiable information.

Endpoint	Method	Description
`/api/pii/getPII/:orderId`	GET	Fetch customer address for order
`/api/pii/blockPII`	POST	Block PII access for order
`/api/pii/completeOrder`	POST	Mark order complete
`/api/pii/getFile`	GET	Retrieve stored file
`/api/pii/writeFile`	PUT	Store file for order
`/api/pii/deleteFile`	DELETE	Remove stored file

Label Proxy

Generate shipping labels through carrier APIs.

Endpoint	Method	Description
`/api/label-proxy/forward`	POST	Forward request to carrier with PII injection

Print

Send labels to Device Hub for printing.

Endpoint	Method	Description
`/api/print/send`	POST	Send labels to printer

Passthrough

Proxy requests to Amazon SP-API.

Endpoint	Method	Description
`/passthrough-api/*`	GET/POST/DELETE	Proxy to whitelisted SP-API endpoints

Notifications

Amazon order change notifications.

Endpoint	Method	Description
`/api/notification/registerNotification`	POST	Subscribe to order changes

Health

System health monitoring.

Endpoint	Method	Description
`/health-check`	GET	Check system status

Response Format

Success Response

{
  "success": true,
  "data": {
    // Response data
  }
}

Error Response

{
  "is_adb_error": true,
  "success": false,
  "error": {
    "message": "Error description",
    "details": "Additional context (optional)"
  }
}

Rate Limits

Scope	Limit	Window
OAuth endpoints	5 requests	10 seconds per IP
PII access	1 request	1 hour per order
File operations	50 requests	24 hours per tenant
General API	Adaptive	Per IP (Arcjet WAF)

HTTP Status Codes

Code	Meaning
200	Success
204	Success (no content)
302	Redirect (OAuth flows)
400	Bad request (validation error)
401	Unauthorized (invalid token)
403	Forbidden (access denied)
404	Not found
429	Rate limited
500	Server error

Quick Links

Tenant Management

Create tenants and get access tokens.

PII Access

Fetch and manage customer data.

Label Proxy

Generate shipping labels.

Passthrough API

Access Amazon SP-API.

API Overview

API Reference