One-time token handoff

One-time token handoff transfers user identity between cTrader and broker systems using short-lived one-time tokens.

Prerequisites

Important

Before implementing One-time token handoff, ensure completion of:

• Setup actions: Infrastructure & connectivity, authentication of API calls
• Contracts: Broker identification, screen URL conventions

Implementation flow

API specifications

Block A: how cTrader passes the token (informational, no broker implementation required)

When a user triggers an embedded broker page (deposit, KYC or custom action), cTrader generates a one-time token internally. This is an internal cTrader operation. The broker receives the token passively: cTrader embeds it in the URL when opening the broker page:

https://{broker-screen-url}?token={otToken}&...

No broker-side API call is required to obtain the token.

Block B: token redemption endpoint (the only broker API call for One-time token handoff)

Field	Value
Caller	Broker backend
Callee	cTrader backend
Method	POST
Path	/ctid2/inAppToken/redeem
Auth	Manager Token appended as ?token={webservToken} (see Authentication of API calls)
Request body	{ "token": "{otToken}" }
Success response (200)	{ "userId": 0, "email": "string", "tradingLogin": 0 }
Token lifetime	Short-lived, single-use
Error 401	Unauthorized
Error 403	Forbidden
Error 404	Token not found, expired or already consumed

Limitations

One-time token handoff covers identity transfer for individual in-app actions. When used on its own, it has the following limitations.

• Spotware remains the identity provider. The broker does not control user creation, login or session management. To own the login experience, use SSO user creation and authorisation instead.
• No long-term session. Each one-time token is short-lived and single-use, scoped to a single action. It does not establish a persistent broker-owned session or a long-term accessToken.
• Some feature modules are unavailable. Modules that require a long-term accessToken are not compatible with One-time token handoff: Embedded cTrader web and In-app ribbons. See the module compatibility matrix.
• Migration is supported. Feature modules deployed under One-time token handoff keep working after migrating to SSO, with no redeployment required. See the migration path.