Skip to content

SSO Integration Guide

Overview

SSO (Single Sign-On) provides link-based sign-in to the trading platform. Normal SSO codes, manager impersonation codes, and legacy direct-token links are separate flows with different parameters and authorization behavior.

Normal SSO Code Flow

Use normal SSO codes when an integration needs to sign an existing customer or trading account into the terminal without creating a manager impersonation session.

  1. An authorized staff integration calls CreateCustomerSSOCode or CreateAccountSSOCode, or the corresponding client REST endpoints.
  2. The server returns a login_url containing sso_code and an expires_in value of 60 seconds. The code is bound to the target brand and is stored as a hash in bounded process memory.
  3. Redirect the user to the returned URL. The terminal removes sso_code from the address bar and exchanges it with POST /sso/exchange using the current terminal authentication mode.
  4. The server rechecks the code issuer's current permission and target visibility, and requires the target brand's configured terminal host to be approved for terminal access. Licensed API admission alone is insufficient. It then returns an ordinary customer or account session. The terminal accepts only the subject type matching its configured login mode.

Each recognized code can be redeemed once, expires after 60 seconds, and is invalidated by a server restart. An exchange attempt consumes a recognized code even if the brand is wrong or current authorization checks fail. If the subject type does not match the terminal mode or exchange fails, the terminal does not replace its stored session token pair; request a new code.

For protocol details, request fields, success examples and errors, see ExchangeSSOCode.

Legacy SSO and impersonation flows

The existing manager impersonation code remains a separate flow and continues to use its existing ?code= query parameter and AuthCustomerByCode. The SSOAuthUser command and POST /sso/auth endpoint are also unchanged; they continue to return an account session directly. Existing direct-token links use their legacy ?token= parameter. Do not interchange code, sso_code, and token.

Existing direct-token flow: request a token

A user from the Aria client sends a request to their backend server.

The backend server sends a request to the platform "ScaleTrade" server.

How to request token?

Get Token via server API

Response Example

{
  "login": 51,
  "leverage": 100,
  "currency": "USD",
  "type": "100",
  "email": null,
  "country": "United States",
  "first_name": null,
  ...,
  "__token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

In response, a login-specific token will be returned.

Token example:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.
eyJpZCI6OTk5OTk5OSwicm9sZSI6NCwicGxhdGZvcm0iOiJsaXZlIn0.
9PY0qxgVqPxdFZGmURIkPTTgEGcrua-g440mtc4dcN0

Existing direct-token flow: redirect to WebTrader

Using the received authorization token, perform a redirect via GET:

https://webtrader.{domain}/?token={token}

iframe example:

<iframe src="https://webtrader.{domain}/?token={token}" title="platform"></iframe>

Existing direct-token flow summary

sequenceDiagram
    participant User
    participant CRM Backend
    participant SSO API
    participant WebTrader

    User->>CRM Backend: Login Request
    Backend->>SSO API: SSOAuthUser
    SSO API-->>CRM Backend: Returns __token
    Backend->>User: Redirect with token
    User->>WebTrader: GET ?token=...
    WebTrader-->>User: Authorized Session

Security Notes

  • Tokens are JWT-based
  • Tokens contain expiration (exp)
  • Always use HTTPS
  • Do not expose master authorization tokens on frontend
  • Backend should handle token generation