会话认证

会话认证的目标是确认程序是否已经具备访问 Client Portal API 的能力，尤其是能否访问 /iserver 下的交易、行情和订单 endpoint。

关键 endpoint

Endpoint	方法	作用
`/sso/validate`	`GET`	校验 SSO session 是否有效。
`/iserver/auth/status`	`POST`	查询 brokerage session 是否已认证。
`/iserver/auth/ssodh/init`	`POST`	初始化或重新打开 brokerage session。
`/tickle`	`POST`	保活 session，并返回认证状态摘要。
`/logout`	`POST`	退出 Gateway session。

Client Portal Gateway 的常见 base URL 是：

https://localhost:5000/v1/api

所以检查认证状态时，请求路径通常是：

POST https://localhost:5000/v1/api/iserver/auth/status

因为 Gateway 默认使用 localhost 自签名证书，开发环境里的 HTTP 客户端可能需要显式信任证书，或在调试时关闭证书校验。生产系统不应把关闭证书校验当作长期方案。

认证状态

/iserver/auth/status 的返回值常见字段如下：

字段	类型	中文解释
`authenticated`	boolean	是否已经完成 brokerage session 认证。
`connected`	boolean	是否已连接到 IBKR 后端。
`competing`	boolean	是否有其他平台或连接正在占用同一用户名的 brokerage session。
`message`	string	认证状态说明，失败或异常时可能有文本。
`fail`	string	查询认证状态失败时的原因。

常见组合：

状态	中文理解	处理
`authenticated=true`、`connected=true`	可访问 brokerage session 相关功能。	继续请求目标 endpoint，并保持 `/tickle`。
`authenticated=false`、`connected=true`	Gateway 连接仍在，但 brokerage session 未认证或已超时。	调用 `/iserver/auth/ssodh/init`。
`authenticated=false`、`connected=false`	Gateway 未连接或 session 已断。	重新登录 Gateway，必要时重启 Gateway。
`competing=true`	其他平台占用了同一用户名的 brokerage session。	退出其他平台，或使用另一个 IBKR 用户名。

初始化 brokerage session

/iserver/auth/ssodh/init 用于初始化 brokerage session。请求体包含两个重要字段：

字段	类型	中文解释
`publish`	boolean	是否立即发送请求。通常应为 `true`。
`compete`	boolean	是否让这次连接竞争并断开其他 brokerage session。使用前要确认不会影响 TWS、移动端或其他程序。

请求体示例：

{
  "publish": true,
  "compete": false
}

compete=false 适合先检查状态；compete=true 可能让该 API 会话优先，并影响同一用户名在 TWS、IB Gateway、IBKR Mobile 或 Client Portal 中的交易会话。

如果你只是想读取非交易类信息，不一定需要主动竞争 brokerage session。如果要访问 /iserver 交易、行情、订单功能，就要确保 brokerage session 已经认证。

程序里建议默认使用 compete=false。只有确认这次 API 会话应该接管交易会话，并且不会打断人工 TWS 或其它自动化程序时，才考虑 compete=true。

保活

Client Portal API session 如果几分钟没有收到请求，会超时。官方建议定期调用 /tickle，常见间隔约 60 秒。

/tickle 的返回中通常包含：

字段	中文解释
`session`	session 标识，可用于 WebSocket cookie 参数等场景。
`ssoExpires`	SSO session 距离过期的毫秒数。
`iserver.authStatus`	brokerage session 的认证状态摘要。
`hmds`	历史数据服务相关状态，可能显示没有桥接或没有历史数据请求。

如果 /tickle 能返回但 iserver.authStatus.authenticated=false，说明保活请求本身通了，但交易会话仍不可用。此时不要继续下单或订阅行情，应回到 /iserver/auth/status 和 /iserver/auth/ssodh/init 的认证流程。

退出登录

/logout 会结束 Gateway session。退出后，继续访问受保护 endpoint 需要重新登录和认证。

不要把 /logout 当作普通错误恢复手段频繁调用。只有确认要释放 session、切换用户名、或重新开始认证流程时再使用。