会话

Client Portal API 的请求不是单纯拿一个长期 token 直接调用。Gateway 启动后，用户需要在浏览器里完成登录和二次认证，然后同一台电脑上的 API 请求会复用这个登录会话。

本页接口适合放在所有 Web API 程序的启动检查里：先确认会话在线，再请求账户、行情、订单等业务接口。

基础地址

本地 Gateway 默认地址：

https://localhost:5000/v1/api

Gateway 使用自签名证书。命令行测试时，curl 通常需要加 -k；正式程序里也需要处理本地证书校验。

常用接口

接口	方法	用途
`/sso/validate`	`GET`	检查 SSO 登录会话是否有效。
`/iserver/auth/status`	`POST`	查看交易服务会话是否已建立。
`/tickle`	`POST`	保活会话，同时返回部分认证状态。
`/logout`	`POST`	退出 Gateway 会话。

认证状态

curl -k -X POST https://localhost:5000/v1/api/iserver/auth/status

常见返回结构：

{
  "authenticated": true,
  "connected": true,
  "competing": false,
  "message": "",
  "serverInfo": {
    "serverName": "示例服务器名",
    "serverVersion": "Build ..."
  }
}

字段解释：

字段	中文说明
`authenticated`	Gateway 会话是否已经通过用户认证。
`connected`	Gateway 是否已经连上 IBKR 后端交易服务。
`competing`	是否存在同一用户的竞争会话。为 `true` 时，可能有其它终端抢占连接。
`message`	认证异常或状态提示。为空通常表示正常。
`serverInfo`	IBKR 后端服务器信息，用于排查连接状态。

会话保活

curl -k -X POST https://localhost:5000/v1/api/tickle

/tickle 的作用是告诉 Gateway：程序仍然在使用会话。它不是登录接口，也不能绕过二次认证。

常见返回结构：

{
  "session": "会话标识",
  "ssoExpires": 360000,
  "collission": false,
  "iserver": {
    "authStatus": {
      "authenticated": true,
      "connected": true
    }
  }
}

程序里可以每隔一段时间调用一次 /tickle，同时检查 authenticated 和 connected。如果它们变成 false，就提示用户重新打开 Gateway 登录页。

成功判断

运行示例后，不要只看 HTTP 状态码。至少要同时检查：

检查项	正常含义
`/sso/validate` 返回成功	浏览器登录会话仍然有效。
`authenticated=true`	brokerage session 已认证，可以继续访问多数 `/iserver` 资源。
`connected=true`	Gateway 已连接 IBKR 后端交易服务。
`competing=false`	同一用户名没有被其它交易平台抢占 brokerage session。

常见问题

现象	常见原因	处理方式
浏览器能打开，接口返回 `403`	请求没有复用 Gateway 登录上下文，或会话已过期	重新访问 `https://localhost:5000` 登录。
`authenticated=false`	用户尚未登录或二次认证未完成	在浏览器完成登录与 2FA。
`connected=false`	登录成功但交易服务会话未建立	等待几秒后重试，或重新登录 Gateway。
`competing=true`	同一用户名在其它终端建立了冲突会话	关闭其它会话，或按页面提示确认该会话。