API authentication

API keys

1. Sign in as org admin or owner.
2. Open API keys → Create key.
3. Copy the secret immediately — it is shown once.
4. Optional: restrict to one workspace and set expiry.

Keys are stored hashed; the prefix apx_live_ identifies live keys in logs.

Request header

X-API-Key: apx_live_<secret>

Bearer tokens (JWT) are not used on the public API — only API keys.

Workspace scope

Key scope	Behaviour
Org-wide	May call any workspace in the org
Workspace-scoped	403 if workspace_id in body/query does not match

IP allowlist (Growth+)

Workspace settings may require requests from allowed IP ranges. API calls from other IPs return 403. Configure under workspace security in the app.

Tier requirements

Feature	Minimum tier
Public API	Growth
API overage billing	Growth
OData / BI feed	Growth

Freemium and Starter keys cannot trigger /api/v1/runs.

Key rotation

1. Create a new key.
2. Update integrations to use the new key.
3. Revoke the old key from API keys.

Expiry warning emails are sent 30 and 7 days before expires_at when SMTP is configured.

Internal vs public API

API	Auth	Audience
/api/v1/*	X-API-Key	Customers, Zapier, ERP
/internal/*	X-Internal-Secret	Forecasting service → BFF callbacks
User routes	JWT cookie/bearer	React frontend

Never expose internal secrets to customers.