ExchangeSSOCode

Description: Exchanges a code created by CreateCustomerSSOCode or CreateAccountSSOCode for an ordinary customer or account session. This is normal SSO, not a manager impersonation session.

Access Control

🔓 No existing session required. Possession of a valid, unexpired code is required.

The request must resolve to the brand to which the code was issued. If request context does not identify the brand, pass the optional brand field following the existing API-brand selection convention. The server rechecks current issuer enablement, the issuer's permission and scope, target visibility and enablement, and brand API admission before it issues a session. The brand's configured terminal host must also be approved for terminal access. API admission alone does not satisfy this check, and the optional brand field does not override it.

Request Parameters

Name	Type	Required	Description
code	string	Yes	Exactly 64 lowercase hexadecimal characters from a normal SSO URL.
brand	string	No	Explicit brand selector where allowed by the existing request-host/API-brand convention. It must resolve to the brand bound to the code.

Request Example

{
  "command": "ExchangeSSOCode",
  "extID": "sso-exchange-1",
  "data": {
    "code": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "brand": "default"
  }
}

Response Parameters

The fields below are returned inside data in the TCP response envelope. The server returns one identity shape according to the code subject.

Name	Type	Description
subject_type	string	customer or account.
customer_id	integer	Customer ID; present only for a customer session.
login	integer	Trading login; present only for an account session.
__token	string	Existing primary JWT session token for normal terminal/server authentication.
__datalake_token	string or null	License-signed Data Lake token for the same principal; may be null if the active v2 signer or current authorization context is unavailable.

Customer response:

{
  "extID": "sso-exchange-1",
  "status": 200,
  "data": {
    "subject_type": "customer",
    "customer_id": 1042,
    "__token": "<HS256 customer session JWT>",
    "__datalake_token": "<EdDSA Data Lake JWT or null>"
  }
}

Account response:

{
  "extID": "sso-exchange-1",
  "status": 200,
  "data": {
    "subject_type": "account",
    "login": 123456,
    "__token": "<HS256 account session JWT>",
    "__datalake_token": "<EdDSA Data Lake JWT or null>"
  }
}

The normal session lifetime is unchanged. Customer responses do not include impersonated_by. For token claims and the difference from the primary session JWT, see the Data Lake token profile.

Codes are single-use and expire after 60 seconds. An exchange attempt consumes a recognized code even if it resolves the wrong brand or later issuer/target checks fail. Codes are stored as hashes in bounded process memory, so a server restart invalidates outstanding codes.

Errors

Status	Error	Description
400	INVALID_DATA	code is missing, is not exactly 64 characters, or brand is not a string.
400	SSO_CODE_INVALID_OR_EXPIRED	Code is unknown, consumed, expired, malformed, or does not match the resolved request brand.
403	SSO_ACCESS_DENIED	Issuer or target is disabled, issuer permission/scope was removed, or target visibility checks fail.
403	BRAND_NOT_AVAILABLE	Target brand is not admitted for licensed API access.
503	LICENSE_NOT_ACTIVE	A required active license lease is unavailable.

This command is separate from AuthCustomerByCode, which exchanges an older manager-created impersonation code.