ExchangeSSOCode

Endpoint

POST /sso/exchange

Description

Exchanges a code created by CreateCustomerSSOCode or CreateAccountSSOCode for an ordinary customer or account session. This is normal SSO, not staff impersonation: the resulting customer session has no impersonated_by field and uses the existing ordinary session lifetime. Both the primary __token and the optional Data Lake token are issued through the normal session token path.

The code is single-use, expires 60 seconds after creation, and is bound to the target brand. Any exchange attempt consumes a recognized code, even if it uses the wrong brand or the current issuer/target checks fail. The server stores only a hash of each code in bounded process memory; a server restart invalidates outstanding codes.

Authorization and brand resolution

An Authorization header is not required; possession of the code is required. Redeem it on the target brand's API host. An optional brand value uses the existing request-host/API-brand resolution rules: on a shared API host, the terminal may forward its configured API brand; otherwise the request host identifies the brand. The resolved brand must match the code's bound brand.

Before issuing the session, the server rechecks that the issuing staff account is still enabled, still has the required SSO grant, and still has visibility to the enabled customer or account. The target and brand must also remain enabled and API-admitted, and the brand's configured terminal host must be approved for terminal access. API admission alone does not approve the terminal host. The optional brand parameter only selects the API request tenant; it does not override this terminal-host approval check.

Body Parameters

{
  "code": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "brand": "default"
}

Field	Type	Required	Description
code	string	Yes	64-character lowercase hexadecimal code from a normal SSO link.
brand	string	No	Explicit API brand selector, such as the terminal's configured brand on a shared API host. It must resolve to the brand bound to the code and pass existing API brand admission. This does not override the configured terminal host's separate terminal-access approval requirement.

Success response

HTTP 200 returns one of these two shapes, depending on the code's subject.

Customer session:

{
  "subject_type": "customer",
  "customer_id": 1042,
  "__token": "<HS256 customer session JWT>",
  "__datalake_token": "<EdDSA Data Lake JWT or null>"
}

Account session:

{
  "subject_type": "account",
  "login": 123456,
  "__token": "<HS256 account session JWT>",
  "__datalake_token": "<EdDSA Data Lake JWT or null>"
}

Field	Type	Description
subject_type	string	customer or account, identifying the session type.
customer_id	integer	Present for a customer session; identifies the customer.
login	integer	Present for an account session; identifies the trading login.
__token	string	Existing primary session JWT used for normal terminal/server authentication.
__datalake_token	string or null	License-signed Data Lake token for the same principal. It may be null when the active v2 signer or current authorization context is unavailable.

No profile fields beyond the selected subject_type and identity ID are returned. A successful customer session does not include impersonated_by. See the Data Lake token profile for token format and verification requirements.

Errors

HTTP	Error	Description
400	INVALID_DATA	code is missing, is not exactly 64 characters, or brand is not a string. Non-hexadecimal or uppercase code values are rejected as invalid/expired codes by the code store.
400	SSO_CODE_INVALID_OR_EXPIRED	Code is unknown, consumed, expired, or the resolved request brand does not match the bound brand.
403	SSO_ACCESS_DENIED	Issuer or target is no longer enabled, the issuer grant/scope was removed, or current target visibility checks fail.
403	BRAND_NOT_AVAILABLE	Target brand is not admitted for licensed API access.
503	LICENSE_NOT_ACTIVE	The required license lease is not active.

This method is distinct from AuthCustomerByCode, which exchanges a manager impersonation code and returns an impersonated customer session.