Embedded cTrader web

Embedded cTrader web enables brokers to integrate the full trading platform directly within their client area.

Prerequisites

Important

Before implementing Embedded cTrader web, ensure completion of:

• Setup actions: Infrastructure & connectivity, authentication of API calls
• Contracts: Broker identification, screen URL conventions
• Identity options: SSO user creation and authorisation

note

Embedded cTrader web requires long-term accessToken and therefore is only compatible with SSO user creation and authorisation.

Architecture

1. Embedded cTrader web runs inside an iframe (web) or WebView (native mobile).
2. The broker controls the container; cTrader Web is loaded as a standalone URL with authentication parameters in the query string.
3. Authentication uses the SSO OT token path: the broker generates a one-time token immediately before opening cTrader Web.
4. cTrader Web exchanges the one-time token for a long-term accessToken on first load.

Flow diagram

The flow proceeds through the following stages:

1. The user is successfully authorized inside the broker’s CRM system.
2. The user launches cTrader Web from within the broker's client area.
3. The broker’s backend generates an OT token.
4. The browser opens cTrader Web in an iframe, passing the OT token as the token parameter. As an example, cTrader Web can be opened via the link. For the full list of valid cTrader Web deeplinks, see Universal deeplinks.
5. cTrader Web opens a connection to the cTrader backend and sends an authorisation request with the OT token to authorise the corresponding user.
6. The cTrader backend sends a request to exchange the OT token for a long-term access token (POST /oauth2/onetime/authorize).
7. The broker CRM verifies the token and responds with the userId and the long-term accessToken (POST /oauth2/onetime/authorize).
8. The cTrader backend authorises the session under the provided userId and confirms successful authorisation to cTrader Web.
9. cTrader Web stores the accessToken for future usage and begins authorised communications with the cTrader backend.

Endpoints used

Added by this module

None. Embedded cTrader web opens the platform using a token obtained through the identity option; it introduces no broker → cTrader endpoints of its own.

Via the identity option

Embedded cTrader web is compatible only with SSO user creation and authorisation, and the flow relies on its token endpoint:

• POST /oauth2/onetime/authorize — verify and exchange the OT token for a long-term access token

URL parameters and options

Required parameters

Parameter	Required	Description
token	Yes	One-time authentication token from broker CRM
source	Yes	Platform source identifier (typically "web")

Optional parameters

Parameter	Required	Description
lang	No	Language code (en, es, fr, etc.)
acc	No	Specific trading account number
theme	No	Theme preference (light, dark)
utm_*	No	UTM tracking parameters

Example URLs

<iframe src="https://app.ctrader.com/info?source=web&token=f44bade2-2138-47c2-89e6-ce978bcca028&lang=en"></iframe>
<iframe src="https://app.ctrader.com/info?source=web&token=f44bade2-2138-47c2-89e6-ce978bcca028&lang=en&acc=8003098&theme=dark"></iframe>
<iframe src="https://app.ctrader.com/info?source=web&token=f44bade2-2138-47c2-89e6-ce978bcca028&lang=en&utm_source=crm&utm_campaign=trading_launch"></iframe>

Implementation requirements

Broker CRM

• Generate a valid OT token immediately before opening cTrader Web: tokens are single-use and must not be cached or reused across sessions.
• Implement POST /oauth2/onetime/authorize to verify the OT token and return userId and accessToken (see POST /oauth2/onetime/authorize).
• Store the user's preferred language to ensure correct localisation of the embedded platform.

Frontend

• Embed cTrader Web in an iframe (web) or open it in a dedicated WebView (mobile) using the URL format defined in URL parameters and options.
• Pass token and source as required parameters on every load.

Error handling

Scenario	Cause	Resolution
cTrader Web fails to authenticate on load	OT token is invalid, malformed or already consumed	Generate a new OT token and reload the iframe
OT token rejected with 410	Token has expired before cTrader Web could use it	Generate a new OT token and reload the iframe
OT token rejected with 403 CH_CLIENT_AUTH_FAILURE	Invalid crmApiToken on POST /oauth2/onetime/authorize	Re-authenticate the cTrader backend via POST /oauth2/crmApiToken
OT token rejected with 417 CID_NON_EXISTED_TOKEN	An invalid or non-existent token was passed to the broker backend	Verify the OT token returned by POST /oauth2/onetime/authorize