版本 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。