Skip to main content
Tradara supports two authentication mechanisms. Choose the one that matches your integration: The gateway (https://api.tradara.com) validates every request, resolves scope, and forwards to downstream services. Calls that miss or fail authentication return 401 Unauthorized.

​
Firm API key

Send your secret on every request using one of:
Both headers carry the same value. Pick one per request — don’t send both.

​
Firm scope

The gateway derives firm_id from the API key and injects X-Firm-ID for downstream services that require it (firm-control, admin-query). You should not set X-Firm-ID yourself when using a firm API key.

​
Routes that reject firm keys

A firm key cannot reach trader-only surfaces. Calls to these paths return 403 Forbidden:
  • /v1/auth/* — user login, refresh, MFA
  • /v1/market-data/* and /v1/ws — terminal data and trader WebSocket
  • /v1/firm-control/me/* — current-user terminal endpoints
  • /v1/firm-control/firms (list across firms — JWT only)
  • /v1/instruments/* — symbol reference (JWT only)
  • /v1/journal/*, /v1/pm/*, /internal/* — terminal and internal surfaces
For everything else under /v1/orders, /v1/fills, /v1/trades, /v1/balances, /v1/accounts/*/positions, /v1/positions, /v1/stats, /v1/firm-control/* (excluding /me/*), and /v1/admin/query/*, the firm key is allowed.

​
Storage

​
JWT session

Trader-facing applications (the Tradara terminal, your custom front-end) sign users in through /v1/auth/* and receive a session cookie plus a bearer token. Send the token on subsequent requests:
The Trading API works with a JWT when the authenticated user owns the target account. The terminal WebSocket /v1/ws is JWT-only — firm keys cannot connect. The detailed login, refresh, and MFA flows are not part of this reference. See the terminal SDK if you are embedding a trader experience.

​
Idempotency

POST /v1/orders accepts an Idempotency-Key header so order placement is safe to retry over flaky networks:
Rules:
  • The key is scoped per firm. Reusing a key returns the original response.
  • The retention window is 24 hours.
  • Use a fresh UUIDv4 (or any sufficiently unique token) per logical order placement.
  • If the request body differs from the stored request for the same key, the gateway returns 409 Conflict.
Idempotency is not honoured on PATCH, DELETE, or non-order writes. Those endpoints are either idempotent by nature (cancel) or are not retry-safe.

​
Request format

  • All bodies are JSON. Set Content-Type: application/json.
  • Timestamps are Unix milliseconds (integer) unless explicitly labelled ISO 8601.
  • Money fields are decimal strings ("123.45") — never floats — to avoid precision loss.
  • UUIDs are lowercase, hyphenated.

​
Common error responses

See Errors for the full envelope and codes.