All Retrac API requests must use HTTPS. Unencrypted HTTP is not supported.
API keys
Create keys under Settings → API Keys in your workspace. Each key is tied to the user who created it and inherits that user’s workspace role and location access.
Authorization: Bearer YOUR_API_KEY
API keys are shown once at creation. Store them in a secrets manager or environment variable. Never commit keys to source control, client-side code, or public repositories.
Key types
| Type | Prefix | Workspace ID | Scopes |
|---|
| Full access | (no prefix) | Required on every request via workspaceId query param | All permissions your user role allows |
| Restricted | retrac_ | Embedded in the key — omit workspaceId | Only scopes you select at creation |
Scopes
Restricted keys use space-separated scopes. Presets in the dashboard map to:
| Preset | Scopes | Use when |
|---|
| All access | apis.all | Trusted server-side integrations needing full inventory access |
| Read only | apis.read | Reporting, dashboards, sync-from-Retrac jobs |
| Restricted | Custom subset | Principle of least privilege |
| Scope | Allows |
|---|
items.read / items.write | List and manage catalog items |
tags.read / tags.write | List and manage tags |
locations.read / locations.write | List and manage locations (write is owner-only) |
inventory.read / inventory.write | Read balances/movements; set on-hand stock |
transfers.read / transfers.write | List and create transfers; owners may revert |
workspaces.read / workspaces.write | Read workspace metadata; update workspace (write is owner-only) |
locations.write if their role does not include that permission.
Workspace ID
Full-access keys must pass workspaceId on every workspace-scoped request:
https://api.retrac.co/items?workspaceId=YOUR_WORKSPACE_ID
retrac_…) are bound to one workspace — do not pass workspaceId; the server resolves it from the key.
Session authentication
Dashboard session cookies are not documented here and should not be used for third-party integrations. Use API keys for programmatic access.
Plan requirements
API keys are available on Business plans and above. Lower plans may receive 403 responses when creating or using keys. 
