Create embed session

POST /v1/firm-control/embed-sessions

Mints a single-use bootstrap token and returns a ready-to-load embed_url for the Tradara terminal /embed route. Call this from your backend when a trader opens your embedded trading experience. See Terminal embed overview for the full iframe integration flow.

Authentication

Firm API key with embed:write scope, or staff JWT with equivalent firm permission.

Headers

Header	Notes
`X-Tradara-Api-Key`	Firm API key (`tdr_live_…` or `tdr_test_…`).
`X-Firm-ID`	Firm UUID. Auto-injected for firm API keys.

Body

Field	Type	Required	Notes
`email`	string (email)	one of `email` / `user_id`	Trader email.
`user_id`	string (UUID)	one of `email` / `user_id`	Existing Tradara user UUID.
`layout_template_id`	string (UUID)	no	Firm layout template to apply on load. Must belong to your firm.
`account_ids`	string[]	conditional	Ignored when firm `metadata.embed_account_scope` is `all` (default). Required when scope is `explicit`. See Configure account scope.

The user must have an ACTIVE TRADER relationship with your firm. Your firm must have metadata.allowed_embed_origins configured — see Configure allowed origins.

Example (all firm accounts — recommended)

curl -X POST "$TRADARA_BASE_URL/v1/firm-control/embed-sessions" \
  -H "X-Tradara-Api-Key: $TRADARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "layout_template_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

Omit account_ids so the iframe loads every account the trader has at your firm. With the default firm setting (embed_account_scope: "all"), any account_ids you send are ignored.

Example (explicit account list)

Only when the firm has metadata.embed_account_scope: "explicit":

curl -X POST "$TRADARA_BASE_URL/v1/firm-control/embed-sessions" \
  -H "X-Tradara-Api-Key: $TRADARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "account_ids": ["5b1c8a2e-9f2d-4d3c-b6f0-2b6c5b6e1f9a"]
  }'

Response — `200 OK`

{
  "embed_url": "https://terminal.tradara.com/embed?et=AbCdEf...",
  "expires_at": "2026-07-08T00:15:30Z"
}

Field	Notes
`embed_url`	Load this URL in an `<iframe src="...">`. The `et` parameter is single-use and short-lived (~60 seconds).
`expires_at`	RFC 3339 UTC timestamp when the bootstrap token expires.

Errors

HTTP	Meaning
`400`	Missing `email`/`user_id`, unknown `layout_template_id`, firm has no `allowed_embed_origins`, or missing `account_ids` when `embed_account_scope` is `explicit`.
`403`	Missing `embed:write`, or user is not an active trader for the firm.
`502`	Downstream auth or identity service unreachable.
`503`	Required downstream client not configured.

Integration notes

Do not log or persist full embed_url values in analytics — treat et as a secret bootstrap credential.
Do not embed the URL in emails or long-lived static pages. Mint on demand when the trader navigates to your trading UI.
Minting a new session for the same trader invalidates any prior embed session for that trader at your firm.
After exchange, the terminal manages embed JWT refresh. Your backend does not need to proxy trading API calls for the iframe.

Overview

Account Provisioning

Terminal Embed

Firm & Users

Staff & RBAC

Offerings & Acceptance

API Keys

Webhooks

Realtime WebSocket

Operations

Firm Backoffice Reads

Terminal Onboarding (JWT)

Create embed session

Authentication

Headers

Body

Example (all firm accounts — recommended)

Example (explicit account list)

Response — `200 OK`

Errors

Integration notes

​Authentication

​Headers

​Body

​Example (all firm accounts — recommended)

​Example (explicit account list)

​Response — 200 OK

​Errors

​Integration notes

Authentication

Headers

Body

Example (all firm accounts — recommended)

Example (explicit account list)

Response — `200 OK`

Errors

Integration notes