Terminal embed

Embed the Tradara terminal on your prop firm website so traders can chart and trade without leaving your portal. Your backend mints a short-lived bootstrap URL; the trader’s browser loads it in an <iframe>; Tradara exchanges the token server-side and issues a restricted embed session.

Embed is not a replacement for the Trading API. Use embed when you want Tradara’s hosted terminal UI inside your site. Use the Trading API when you build your own order entry and dashboards.

How it works

Configure allowed_embed_origins on your firm record — in Backoffice → Firm Control → Embed, or via PATCH /v1/firm-control/firm. Optionally set embed_theme_preset for a branded palette.
Provision the trader with an ACTIVE TRADER relationship and at least one account (Account provisioning).
Mint an embed session from your backend with POST /v1/firm-control/embed-sessions. Requires a firm API key with embed:write.
Render the returned embed_url in an <iframe> on a page you control.
The terminal bootstraps inside the iframe, exchanges the single-use et token, and keeps the session alive with embed refresh tokens.

Bootstrap tokens expire in about 60 seconds. Mint the URL immediately before you show the iframe, or when the trader navigates to your trading page — not hours in advance.

Prerequisites

Requirement	Notes
Firm API key	`embed:write` scope. See API keys.
Active trader	`user_id` or `email` must resolve to a user with an ACTIVE `TRADER` relationship at your firm.
`allowed_embed_origins`	At least one origin on the firm `metadata` object. See Configure allowed origins.
Optional layout template	Publish a firm layout via `layout_template_id`. See Layout templates.
Optional embed theme	Set `metadata.embed_theme_preset`. See Configure embed theme.
Account scope	Default `metadata.embed_account_scope: "all"` — one embed loads every account the trader has at your firm. See Configure account scope.

Embed an iframe

Mint the session server-side — never expose your firm API key in the browser.

<!-- Your page at https://portal.acme.example/trade -->
<iframe
  id="tradara-terminal"
  src="https://terminal.tradara.com/embed?et=SINGLE_USE_TOKEN"
  title="Tradara"
  style="width: 100%; height: 100vh; border: 0;"
  allow="clipboard-read; clipboard-write"
  referrerpolicy="no-referrer-when-downgrade"
></iframe>

Server-side mint (Node example)

const response = await fetch(`${TRADARA_BASE_URL}/v1/firm-control/embed-sessions`, {
  method: "POST",
  headers: {
    "X-Tradara-Api-Key": process.env.TRADARA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "[email protected]",
    layout_template_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890", // optional
  }),
});

if (!response.ok) throw new Error(await response.text());

const { embed_url, expires_at } = await response.json();
// Pass embed_url to your template or SPA — do not cache it

Treat embed_url like a one-time login link. Generate it when the trader opens the page, or expose a “Open terminal” action that fetches a fresh URL. If the token expires before the iframe loads, mint again.

Security model

Single-use bootstrap token

The et query parameter is consumed on first exchange. Reusing or sharing the URL returns 401. Pending tokens for the same user and firm are invalidated when a new session is minted.

One active embed session per trader per firm

Starting a new embed session for the same trader at the same firm revokes the prior embed access and refresh tokens. A trader cannot hold multiple concurrent embed sessions for your firm.

Firm-scoped API access

Embed sessions receive short-lived JWTs with session_type: embed. The API gateway injects X-Session-Type, X-Firm-ID, and optional X-Embed-Account-IDs. Embed tokens can call trading and market-data routes (orders, positions, balances, /v1/ws, and related reads), plus market-data onboarding (/v1/profiles, /v1/address, /v1/agreements, entitlements classification, and /v1/firm-control/me/market-data-onboarding/*). They cannot call Prop Firm admin APIs, journal, layout sharing, or full-terminal auth flows.

Origin allowlist

At exchange time, Tradara checks the browser Origin header against allowed_embed_origins stored on your firm when the token was minted.

allowed_embed_origins lists Tradara terminal origins (where /embed is hosted), not your website’s domain. The exchange request is sent from JavaScript running inside the iframe — its Origin is the terminal host (for example https://terminal.tradara.com), not https://portal.acme.example.

Your portal can live on any HTTPS origin. Tradara sets Content-Security-Policy: frame-ancestors * on /embed so third-party sites may frame the terminal.

Account scoping

By default (embed_account_scope: "all", or unset), one iframe exposes every account the trader can access at your firm. Traders switch accounts inside the embed — you do not need a separate session per account. Set embed_account_scope: "explicit" only when you want 1:1 iframes; then each mint must pass account_ids. See Configure account scope.

Session lifetimes

Token	Typical lifetime	Purpose
Bootstrap (`et`)	~60 seconds	One-time URL parameter; exchanged on iframe load
Embed access JWT	~15 minutes	Bearer token for API and WebSocket calls inside the terminal
Embed refresh token	~1 hour	Rotated via `POST /v1/auth/embed/refresh` to extend the session

The terminal handles refresh automatically. Traders do not sign in with username and password inside the embed.

Endpoints

Method	Path	Page
`POST`	`/v1/firm-control/embed-sessions`	Create embed session
`GET`	`/v1/firm-control/layout-templates`	Layout templates
`POST`	`/v1/firm-control/layout-templates`	Layout templates
`PATCH`	`/v1/firm-control/firm`	Configure allowed origins

Public auth routes (POST /v1/auth/embed/exchange, POST /v1/auth/embed/refresh) are called by the terminal — your integration does not call them directly.

Common errors

Symptom	Likely cause
`403 embed:write permission required`	API key missing `embed:write`.
`400 firm has no allowed_embed_origins configured`	Set `metadata.allowed_embed_origins` before minting.
`403 user is not an active trader for this firm`	Invite or provision the trader first.
`403 origin not allowed for this embed token`	Terminal origin not in `allowed_embed_origins`.
`401 invalid, expired, or already used embed token`	Bootstrap token expired or iframe loaded twice. Mint a fresh URL.
Blank iframe / CSP `frame-ancestors 'none'`	Terminal host must serve only `frame-ancestors *` on `/embed` (not also `'none'`). Firm allowlist is unrelated — list the Tradara terminal origin, not your portal.
Embed loads but shows Sign in / no accounts	Confirm Network shows `POST /v1/auth/embed/exchange` then authenticated `GET /v1/accounts/...` with `Authorization: Bearer`. No `Set-Cookie` is expected — embed uses bearer tokens in `sessionStorage`.

Overview

Account Provisioning

Firm & Users

Staff & RBAC

Offerings & Acceptance

API Keys

Webhooks

Realtime WebSocket

Operations

Firm Backoffice Reads

Terminal Onboarding (JWT)

Terminal embed

How it works

Prerequisites

Embed an iframe

Server-side mint (Node example)

Security model

Single-use bootstrap token

One active embed session per trader per firm

Firm-scoped API access

Origin allowlist

Account scoping

Session lifetimes

Endpoints

Common errors

​How it works

​Prerequisites

​Embed an iframe

​Server-side mint (Node example)

​Security model

​Single-use bootstrap token

​One active embed session per trader per firm

​Firm-scoped API access

​Origin allowlist

​Account scoping

​Session lifetimes

​Endpoints

​Common errors

How it works

Prerequisites

Embed an iframe

Server-side mint (Node example)

Security model

Single-use bootstrap token

One active embed session per trader per firm

Firm-scoped API access

Origin allowlist

Account scoping

Session lifetimes

Endpoints

Common errors