FTLib
版本 v1.4 最后更新:2026-11-13

鉴权与密钥|Bearer Token 与推送鉴权 - FTLib

FTLib 使用 API Key 控制访问。密钥按数据域与配额授权,REST 与 WebSocket 使用同一把密钥,但鉴权方式不同。

REST 鉴权

在每个请求的 Authorization 头中携带 Bearer Token。不要将密钥放在 URL 查询参数中,避免出现在日志与浏览器历史里。

bash
curl -H "Authorization: Bearer $FTLIB_API_KEY" \
  "https://api.ftlib.com/v1/quote/snapshot?symbols=600519.SH"
鉴权相关状态码
状态码含义处理建议
401缺少密钥或密钥无效检查请求头格式与密钥是否过期
403密钥有效但无该数据域权限核对授权范围或联系支持
429超过配额或 QPS 限制降低频率并按退避策略重试

推送鉴权

WebSocket 连接建立后,客户端需在限定时间内发送 auth 消息。鉴权成功前不要发送订阅请求。鉴权失败会关闭连接,错误原因通过关闭帧或错误消息返回。

json
{
  "op": "auth",
  "key": "your_api_key"
}
鉴权超时 连接建立后若未在规定时间内完成鉴权,服务端会主动断开。客户端应在 onopen 后立即发送鉴权消息,并在心跳中保持连接活跃。

权限边界

密钥权限由接入方案决定,常见维度包括数据域、证券范围、历史深度、并发连接数与 QPS。权限不足时,REST 返回 403,推送订阅会被拒绝或只返回已授权部分。

  • 行情、基本面、基金与可转债可以分别授权。
  • L2 逐笔数据通常单独授权,并限制历史查询深度。
  • 并发推送连接数与订阅代码数量受配额约束。
  • 测试密钥与生产密钥应分离,避免测试流量影响生产配额。

密钥轮换

建议定期轮换密钥,并在轮换期间保留短暂的双密钥并行窗口。步骤:创建新密钥、更新服务配置、验证新密钥可用、观察错误率、停用旧密钥。

轮换检查 轮换后至少验证 REST 快照、历史查询与推送订阅三类调用,确认权限与配额均正常,再停用旧密钥。

安全建议

  • 通过环境变量或密钥管理服务注入密钥,不要硬编码。
  • 服务端调用,不要把密钥暴露在浏览器或移动端。
  • 为不同环境使用不同密钥,限制单把密钥的权限范围。
  • 记录调用量与错误率,发现异常流量时及时轮换。
  • 如怀疑密钥泄露,立即停用并联系 support@ftlib.com。