认证

Client Portal API 的认证不是单纯拿到一个 token 就结束。它至少要区分两层会话：外层的 Portal session，以及能访问交易、行情和 /iserver endpoint 的 brokerage session。

官方 Client Portal API 文档入口：Client Portal API v1.0 Documentation。

两层会话

会话	中文理解	能做什么
Portal session	外层 Web 登录会话，也可理解为只读或基础 Web 会话。	访问部分非 `/iserver` endpoint，例如部分账户、组合或 Client Portal 资料。
Brokerage session	交易会话，也就是连接 IBKR 后端交易系统的会话。	访问 `/iserver` 相关 endpoint，包括行情、订单、成交、交易状态等。

/iserver 资源通常都要求 brokerage session。如果只登录了外层 Portal session，很多交易相关请求会返回未认证、未连接或 session 不完整。

方式	适用场景
Client Portal Gateway	个人账户、本地开发、需要通过浏览器登录并完成 2FA 的场景。
OAuth 1.0a	部分第三方和旧版授权流程。
OAuth 2.0	官方统一 Web API 方向的授权方式。
SSO	特定集成或 Gateway / OAuth 相关流程中使用。

个人账户使用 Client Portal Gateway 时，登录页面和 Client Portal 登录体验类似，需要账号密码和双因素认证。官方不提供给个人客户自动化 Gateway brokerage session 登录的机制。

认证是否成功，不应该靠“浏览器页面看起来登录了”或“HTTP 请求返回 200”判断。应该请求认证状态 endpoint：

Endpoint	方法	用途
`/iserver/auth/status`	`POST`	查询该 brokerage session 是否已认证、是否连接、是否存在竞争会话。
`/sso/validate`	`GET`	校验 SSO session，适用于 Client Portal Gateway 和 OAuth 2.0 客户端。
`/tickle`	`POST`	保活并返回 session 信息，同时包含 `/iserver/auth/status` 的认证状态。

在 Client Portal Gateway 模式下，文档中的 endpoint 通常拼接在 Gateway 的 API base URL 之后，例如：

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

如果使用 OAuth 或官方统一 Web API 入口，base URL、认证头和可用 endpoint 以对应接入文档为准。

字段	中文解释
`authenticated`	brokerage session 是否已认证。行情、订单和多数 `/iserver` 功能依赖它为 `true`。
`connected`	Gateway 是否连接到 IBKR 后端。连接成功不代表已认证。
`competing`	是否存在竞争 brokerage session，例如同一用户名在 TWS、Client Portal 或移动端占用了交易会话。
`message`	认证状态说明。认证成功时通常为空。
`serverInfo`	IBKR 后端服务器信息，排查时可记录但展示给用户时通常不重要。

确认 Gateway 仍在运行，并能打开 https://localhost:5000。
确认浏览器已完成账号密码和 2FA。
调用 /sso/validate 检查外层 SSO session。
调用 /iserver/auth/status 检查 brokerage session。
如果 connected=true 但 authenticated=false，调用 /iserver/auth/ssodh/init 初始化 brokerage session。
如果 competing=true，退出其他 IBKR 平台或使用另一个用户名。
使用 /tickle 定期保活，避免 5 分钟左右无请求导致 session 超时。

认证检查建议写成独立函数，不要混在下单、行情或账户读取逻辑里。这样 session 失效、竞争会话和权限不足可以分别处理，日志也更清楚。