Skip to main content

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"

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