Skip to main content

One-time token handoff

One-time token handoff provides a minimal integration approach using short-lived one-time tokens to transfer user identity between cTrader and broker systems. This module is ideal for brokers without OAuth-capable CRM systems or those seeking a lightweight integration path.

Overview​

The One-time token handoff module enables:

  • Minimal integration requirements
  • One-time token-based identity transfer
  • Rapid deployment with reduced complexity
  • Compatibility with existing broker systems
  • Lower implementation overhead compared to Full SSO

Prerequisites​

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

  • Prerequisites: All foundation requirements (infrastructure, authentication, broker identification, URL conventions, error codes)

Architecture​

Token-Based Identity Transfer​

Unlike Full SSO where the broker owns user identity, One-time token handoff uses cTrader as the primary identity provider with broker systems receiving temporary identity information via one-time tokens.

Key Components​

  • cTrader Identity Provider: Maintains user authentication and identity
  • One-Time Token System: Short-lived tokens for identity transfer
  • Broker Screen Integration: Minimal screens for specific actions
  • Token Validation: Secure token exchange mechanisms

Implementation Flow​

Stage 1: User Authentication in cTrader​

  1. User authenticates in cTrader

    • Standard cTrader login process
    • Identity managed by cTrader backend
    • Session established in cTrader

  2. User initiates broker-requiring action

    • Clicks deposit button in cTrader
    • Initiates KYC process
    • Accesses broker-specific feature

Stage 2: One-Time Token Generation​

  1. cTrader backend generates OT token

    • Endpoint: /ctid2/inAppOneTimeToken/data
    • Method: GET
    • Authentication: User session token

  2. Token includes user context

    • User identifier (userId)
    • Email address
    • Trading login (if applicable)
    • Action context (deposit, KYC, etc.)

Stage 3: Broker Screen Integration​

  1. cTrader opens broker screen with OT token

    • URL: https://brokerCrmUrl.com/inapp/{action}
    • Parameter: token={otToken}
    • Additional context parameters

  2. Broker screen validates OT token

    • Validation Endpoint: Internal broker API
    • Token Verification: Check token validity and user context
    • User Identification: Extract user information from token

Stage 4: Action Processing​

  1. Broker processes requested action

    • Displays appropriate screen for action
    • Pre-populates with user information from token
    • Processes user input and completes action

  2. Results returned to cTrader

    • Success/failure status
    • Action results (deposit confirmation, KYC status)
    • Optional callback to cTrader backend

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 resolution endpoint (the only broker API call for One-time token handoff)​

FieldValue
CallerBroker backend
CalleecTrader backend
MethodGET
Path/ctid2/inAppOneTimeToken/data
AuthManager Token appended as ?token={webservToken} (see Authentication of API calls)
Request paraminAppOneTimeToken={otToken}
Success response{ userId, traderId, brokerName, accountId }
Token lifetimeShort-lived, single-use
Error 404Token not found — invalid or malformed
Error 410Token expired or already consumed

Required Screens​

Deposit Screen​

  • URL: /inapp/deposit
  • Parameters: token, account (optional)
  • Functionality: Deposit processing with user pre-identification

KYC Screen​

  • URL: /inapp/kyc
  • Parameters: token
  • Functionality: KYC process with user context

Generic Action Screen​

  • URL: /inapp/action
  • Parameters: token, actionType
  • Functionality: Custom broker actions

Chat/Support Screen​

  • URL: /inapp/chat
  • Parameters: token
  • Functionality: Support integration with user identity

URL Examples​

Deposit Action​

https://brokerCrmUrl.com/inapp/deposit?token=abc123&account=67890&lang=en

KYC Action​

https://brokerCrmUrl.com/inapp/kyc?token=xyz789&lang=es&source=Mobile

Support Chat​

https://brokerCrmUrl.com/inapp/chat?token=def456&theme=dark

Error Handling​

Invalid Token​

{
    "error": "Invalid Token",
    "message": "The provided token is invalid or expired",
    "code": "INVALID_OT_TOKEN"
}

Token Expired​

{
    "error": "Token Expired", 
    "message": "The provided token has expired",
    "code": "TOKEN_EXPIRED"
}

User Not Found​

{
    "error": "User Not Found",
    "message": "User context not found in token",
    "code": "USER_NOT_FOUND"
}

Limitations​

Compared to SSO User creation and authorisation​

  • No Broker Identity: cTrader remains primary identity provider
  • Limited User Management: No broker-owned user accounts
  • Reduced Control: Limited broker control over authentication
  • Session Dependency: Relies on cTrader session validity

Feature Limitations​

  • No Auto Re-Login: Requires cTrader authentication each time
  • Limited Partner Attribution: No comprehensive partner tracking
  • Reduced Analytics: Limited user journey tracking
  • No Unified Branding: cTrader branding remains primary

Use Cases​

Ideal Scenarios​

  • Brokers without OAuth CRM: Systems without OAuth capabilities
  • Quick Pilot Programs: Testing integration before full SSO
  • Specific Feature Integration: Adding individual features like deposits
  • Legacy System Integration: Working with older CRM systems

Common Applications​

  • Deposit Integration: Add deposit functionality to cTrader
  • KYC Integration: Embed KYC processes in trading platform
  • Support Integration: Connect support systems with user context
  • Custom Actions: Implement broker-specific actions

Migration Path​

To SSO User creation and authorisation​

One-time token handoff can serve as a stepping stone to SSO User creation and authorisation:

  1. Start with One-time token handoff for quick deployment
  2. Add OAuth capabilities to broker CRM
  3. Migrate to SSO User creation and authorisation for comprehensive identity management
  4. Maintain both systems during transition period