Skip to main content

A.3 Broker Identification

Consistent broker identification across all API calls and URL patterns is essential for proper routing, validation, and operational management. This section defines the standardized parameters and their usage throughout the SSO (OAuth) solution.

Broker Identification Parameters​

The API calls defined in the SSO (OAuth) solution take several request body keys and/or query parameters the values of which are provided by Spotware Systems on a per-broker basis.

ParameterData TypeDescription
brokerCrmNamestringA unique name designating a broker's CRM system. If several brokers share the same CRM system, they will also have the same brokerCrmName value.
brokerNamestringA unique name denoting a specific broker (including White Labels).

Parameter Usage Guidelines​

brokerCrmName​

  • Purpose: Identifies the CRM system serving multiple brokers
  • Scope: Shared across brokers using the same CRM infrastructure
  • Usage: Used for system-level routing and configuration
  • Example: tradingtech_crm, financialhouse_crm

brokerName​

  • Purpose: Identifies individual broker entities
  • Scope: Unique per broker, including white label configurations
  • Usage: Used for broker-specific routing, reporting, and configuration
  • Example: tradingtech_main, tradingtech_wl_europe

Implementation Requirements​

Consistent Usage​

Both parameters must be used consistently across:

  • All API request bodies
  • URL query parameters
  • Callback URL validation
  • Error reporting and logging
  • Analytics and tracking

URL Pattern Integration​

Broker identification parameters should be incorporated into:

  • Authentication endpoints
  • User creation and authorization flows
  • InApp action URLs
  • Callback validation mechanisms
  • Error handling contexts

Validation Rules​

  • Required Fields: Both parameters are mandatory for proper operation
  • Format Validation: Parameters must match exactly values provided by Spotware
  • Case Sensitivity: Parameter values are case-sensitive
  • Character Restrictions: Follow standard URL-safe character sets

URL Template Examples​

Authentication URLs​

https://brokerCrmUrl.com/oauth2/crmApiToken?brokerName={brokerName}&brokerCrmName={brokerCrmName}

User Creation Callbacks​

https://brokerCrmUrl.com/sso/callback?brokerName={brokerName}&brokerCrmName={brokerCrmName}&token={otToken}

InApp Action URLs​

https://brokerCrmUrl.com/inapp/deposit?brokerName={brokerName}&brokerCrmName={brokerCrmName}&token={otToken}&account={accountId}

Error Handling​

Missing Parameters​

  • Error Code: BROKER_ID_MISSING
  • Response: HTTP 400 Bad Request
  • Message: "Required broker identification parameters missing"

Invalid Parameters​

  • Error Code: BROKER_ID_INVALID
  • Response: HTTP 401 Unauthorized
  • Message: "Invalid broker identification parameters"

Mismatched Parameters​

  • Error Code: BROKER_ID_MISMATCH
  • Response: HTTP 403 Forbidden
  • Message: "Broker identification parameters do not match expected values"

Security Considerations​

Parameter Validation​

  • Always validate broker identification parameters against expected values
  • Implement strict matching to prevent parameter injection attacks
  • Use parameter validation as part of overall security framework

Logging and Monitoring​

  • Log all API calls with broker identification parameters
  • Monitor for unusual patterns or parameter combinations
  • Implement alerting for invalid or missing broker parameters

Configuration Management​

  • Store broker identification parameters securely
  • Implement proper access controls for parameter management
  • Regularly review and validate parameter assignments

Multi-Broker Scenarios​

Shared CRM Systems​

When multiple brokers share the same CRM system:

  • brokerCrmName will be identical across all brokers
  • brokerName will be unique for each broker
  • Implement proper routing based on brokerName

White Label Configurations​

For white label deployments:

  • Each white label gets a unique brokerName
  • brokerCrmName may be shared with parent broker
  • Implement proper isolation between white labels

Integration Testing​

Test Cases​

  • Valid broker identification parameters
  • Missing broker identification parameters
  • Invalid broker identification parameters
  • Mixed valid/invalid parameter combinations
  • Case sensitivity testing

Validation Checklist​

  • Parameters are included in all API calls
  • Parameter values match Spotware-provided values exactly
  • URL validation includes broker identification checks
  • Error handling covers all parameter validation scenarios
  • Logging includes broker identification for audit trails

This standardized broker identification system ensures proper routing, security, and operational management across all SSO (OAuth) components and integrations.