Skip to main content

Screen URL conventions and query parameters

Standardized URL patterns and query parameters ensure consistent behavior across all SSO (OAuth) screens and InApp actions. This section defines the conventions for URL structure, parameter handling, and screen integration.

URL Structure Standards​

Base URL Requirements​

All SSO (OAuth) screens must be hosted at consistent endpoints relative to the broker's CRM URL:

  • Base Pattern: https://brokerCrmUrl.com/
  • Consistency: Avoid mixing domains (e.g., broker.com and my.broker.com)
  • SSL Required: All URLs must use HTTPS protocol

Screen URL Patterns​

Login/Signup Screen​

https://brokerCrmUrl.com/auth/login

Trading Account Creation​

https://brokerCrmUrl.com/account/create

InApp Action Screens​

https://brokerCrmUrl.com/inapp/{action}

Success/Callback URLs​

https://brokerCrmUrl.com/callback/success

Mandatory query parameters​

Core Parameters​

ParameterScreen(s)Required?Data TypeDescription
tokenInApp actionsYesstringThe OT token required for authorisation.
accountInApp actionsYes (deposits/withdrawals); No (others)integerThe number of a specific trading account linked to the user.

Optional query parameters​

Display and behaviour parameters​

ParameterScreen(s)Required?Data TypeDescription
langAll screensNostringThe language of the device OS. Takes Alpha-2 (ISO 369-2) codes.
sourceAll screensNostringApplication type: "Web", "Android", "iOS", "MacOS", "Desktop".
themeAll screensNostringPreferred colour scheme: "light" or "dark".
firstLoginLogin/signupNobooleanFlag for first login attempt on current device.
partnerIdLogin/signupNostringEmail assigned as partner identifier to user/account.

UTM tracking parameters​

ParameterScreen(s)Required?Data TypeDescription
utm_sourceAll screensNostringSource channel for user transfer to OAuth screen.
utm_mediumAll screensNostringContent type that encouraged user to click link.
utm_campaignAll screensNostringMarketing campaign name for user transfer.
utm_termAll screensNostringKeyword that user engaged with for transfer.
utm_gclidAll screensNostringGoogle Click identifier for transferred user.

Parameter implementation guidelines​

Language parameter (lang)​

  • Format: Alpha-2 (ISO 369-2) codes (e.g., en, es, fr)
  • Usage: Display forms and screens in appropriate language
  • Fallback: Use default broker language if parameter invalid
  • Storage: Store user language preference in CRM for future sessions

Source parameter (source)​

  • Values: "Web", "Android", "iOS", "MacOS", "Desktop"
  • Usage: Adjust screen design for different device types
  • Responsive Design: Implement mobile-first responsive layouts
  • Feature Detection: Adapt UI capabilities based on source platform

Theme parameter (theme)​

  • Values: "light", "dark"
  • Usage: Maintain consistent design with trading application
  • CSS Variables: Implement theme switching via CSS custom properties
  • Persistence: Store theme preference in user profile

First login parameter (firstLogin)​

  • Values: true, false
  • Usage: Differentiate between user creation and login flows
  • Routing: Route to appropriate page (signup vs login form)
  • Analytics: Track new user acquisition vs returning users

Partner ID parameter (partnerId)​

  • Format: Email address or partner identifier string
  • Usage: Attribute users to specific partners/IBs
  • Validation: Validate partner ID against broker's partner database
  • Attribution: Store partner attribution for commission tracking

URL Examples​

Login screen with parameters​

https://brokerCrmUrl.com/auth/login?lang=en&source=Web&theme=light&firstLogin=true&partnerId=partner@example.com

Mobile login screen​

https://brokerCrmUrl.com/auth/login?lang=es&source=iOS&theme=dark&firstLogin=false

InApp Deposit Screen​

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

KYC Screen with UTM Tracking​

https://brokerCrmUrl.com/inapp/kyc?token=xyz789&lang=fr&utm_source=email&utm_campaign=kyc_reminder

Screen Requirements​

Frontend Implementation​

  • Browser Controls: Screens must not include browser navigation controls
  • Responsive Design: Must work on mobile and desktop layouts
  • Loading Performance: Screen loading times ≤ 3 seconds on common connections
  • Error Handling: Graceful handling of missing or invalid parameters

Content Requirements​

  • Platform References: No mentions of other trading platforms except cTrader
  • Legal Entities: Display correct legal entities and jurisdictions
  • No Pop-ups: Avoid pop-up messages on any screen
  • Clean UI: Organised layout without unnecessary UI elements

Integration Requirements​

  • Parameter Acceptance: All screens must accept required and optional parameters
  • Content Adaptation: Modify page content based on parameter values
  • Callback Handling: Implement proper success/failure callback mechanisms
  • Token Validation: Validate OT tokens for InApp actions

Error Handling​

Missing Parameters​

  • Response: HTTP 400 Bad Request
  • User Action: Display appropriate error message with guidance
  • Fallback: Use default values for non-critical parameters

Invalid Parameters​

  • Response: HTTP 400 Bad Request
  • User Action: Show validation error with correction guidance
  • Logging: Log invalid parameter attempts for security monitoring

Token Issues​

  • Invalid Token: HTTP 401 Unauthorized
  • Expired Token: HTTP 401 Unauthorized with specific message
  • Used Token: HTTP 401 Unauthorized indicating one-time usage