Skip to main content

B.2 Light Identity Handoff

Light Identity 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 Light Identity 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 Light Identity Handoff, ensure completion of:

  • Part A: 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, Light Identity 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​

cTrader Backend Endpoints​

One-Time Token Generation​

GET /ctid2/inAppOneTimeToken/data
Authorization: Bearer {userSessionToken}

Response Example:

{
    "otToken": "abc123xyz789",
    "userId": 12345,
    "email": "user@example.com",
    "tradingLogin": 67890,
    "expiresAt": "2023-01-01T12:05:00Z",
    "action": "deposit"
}

Broker CRM Required Endpoints​

Token Validation Endpoint​

POST /api/validate-token
Content-Type: application/json

Request Body:

{
    "token": "abc123xyz789"
}

Response Example:

{
    "valid": true,
    "userId": 12345,
    "email": "user@example.com",
    "tradingLogin": 67890,
    "expiresAt": "2023-01-01T12:05:00Z"
}

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

Implementation Requirements​

Token Security​

  • Short Lifetime: Tokens expire within 5-15 minutes
  • One-Time Use: Tokens become invalid after first use
  • Secure Generation: Cryptographically secure token generation
  • Validation: Server-side token validation required

Screen Requirements​

  • Minimal UI: Simple screens focused on specific actions
  • Pre-population: Use user data from tokens to pre-fill forms
  • Responsive Design: Mobile and desktop compatibility
  • Error Handling: Graceful handling of invalid tokens

Integration Requirements​

  • Token Validation: Implement secure token validation API
  • User Context: Extract and use user information from tokens
  • Action Processing: Process specific actions based on token context
  • Result Communication: Return action results to cTrader

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"
}

Business Benefits​

For Quick Integration​

  • Rapid Deployment: Minimal implementation requirements
  • Low Complexity: Reduced technical complexity
  • Fast Time-to-Market: Quick integration timeline
  • Cost Effective: Lower development and maintenance costs

For Existing Systems​

  • Non-Disruptive: Works with existing broker systems
  • Flexible: Can be implemented alongside other integrations
  • Scalable: Easy to extend with additional actions
  • Compatible: Works with various CRM architectures

For User Experience​

  • Seamless: Smooth transition from cTrader to broker screens
  • Contextual: User information preserved across systems
  • Efficient: Reduced data entry requirements
  • Consistent: Maintains cTrader session continuity

Limitations​

Compared to Full SSO​

  • 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

Testing Requirements​

Token Testing​

  • Token generation and validation
  • Token expiration handling
  • Token security verification
  • Error scenario testing

Integration Testing​

  • Screen rendering with token context
  • Action processing with user data
  • Error handling for invalid tokens
  • Cross-platform compatibility

Security Testing​

  • Token security validation
  • Injection attack prevention
  • Data protection verification
  • Session security testing

Migration Path​

To Full SSO​

Light Identity Handoff can serve as a stepping stone to Full SSO implementation:

  1. Start with Light Identity for quick deployment
  2. Add OAuth capabilities to broker CRM
  3. Migrate to Full SSO for comprehensive identity management
  4. Maintain both systems during transition period

This Light Identity Handoff approach provides an efficient path to broker integration while maintaining cTrader as the primary identity provider, ideal for rapid deployment and scenarios where full SSO implementation is not immediately feasible.