Authentication
All API requests require authentication via the Authorization header.
Methods
Supabase Session Token
For portal and frontend applications, use a Supabase JWT:
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...This is automatically handled by the portal. The token carries user identity and organization membership.
API Key
For server-to-server and programmatic access:
Authorization: Bearer ord_sk_...API keys are created in Settings > API Keys and are scoped to specific permissions.
Auth Context
Every authenticated request provides an auth context:
| Field | Description |
|---|---|
organizationId | The organization this request is scoped to |
user.id | The user’s ID (undefined for API key auth) |
role | The user’s role: owner, admin, or member |
Scopes
API keys are scoped to limit what they can access. Each endpoint requires specific scopes.
Orders
orders:readView orders and order detailsorders:writeCreate and update ordersShipments
shipments:readView shipments and tracking infoshipments:writeCreate and update shipmentsBridges
bridges:readView bridge configurationsbridges:writeCreate, update, and delete bridgesTransformations
transformations:readView data transformationstransformations:writeCreate and update transformationsWebhooks
webhooks:manageConfigure webhook endpointsCarrier Accounts
carrier-accounts:readView carrier account detailscarrier-accounts:writeManage carrier accountsRates
rates:readFetch shipping ratesPickups
pickups:readView scheduled pickupspickups:writeSchedule and cancel pickupsDispatchers
dispatchers:readView dispatcher rulesdispatchers:writeCreate and update dispatchersOperations
operations:readView operations and itemsoperations:writeCreate and update operationsoperations:executeExecute operations and apply actionsInsights
insights:readView dashboard analytics and reportsinsights:writeConfigure insight settingsAgent
agent:readView agent conversations and memoryagent:writeSend messages to the AI agentagent:adminManage agent settings and standing ordersEmbed
embed:manageManage embed access codes and configError Responses
| Status | Description |
|---|---|
401 | Missing or invalid authentication |
403 | Authenticated but lacking required scope/permission |