API 密钥¶
本页说明"API 密钥"菜单（/account/api-keys）的功能。API Key 是调用数据查询接口的凭证；接口调用方式见 数据接口。
查看 Key 列表¶
登录后进入 API 密钥 页面：
- 显示每个 Key 的名称、前缀（脱敏）、状态（正常 / 已删除 / 已过期）、创建时间、最后使用时间。
- 顶部统计条展示全部密钥、有效、已过期的数量。
- 密钥默认以脱敏形式展示，可按需查看或复制完整 Key；升级前创建的旧密钥需要重新创建。
创建 API Key¶
Key 数量上限由账号权益决定：免费用户 1 个，专业会员不限。删除现有 Key 后可以重新创建。
- 点击 创建 API 密钥。
- 填写：
- 名称：便于识别用途（如 "Python 研究环境"），创建后展示在密钥列表。
- 过期方式：默认 永不过期；需要时可切换为 自定义到期时间，到期后自动失效。
- 提交后新密钥会出现在列表中，可直接查看或复制：
读取权限不再单独配置
创建密钥时无需选择读取权限，新 Key 默认具备全部已公开数据集的读取权限（index:read / quote:read / calendar:read）。
默认不限制账号权益内的指数范围和调用来源；免费用户不支持 IP 白名单，专业会员可在创建或编辑 Key 时按需设置。
可查询范围仍受会员权益和数据时效约束，见 接口总览。
妥善保管 Key
系统使用独立密钥加密保存可再次查看的 API Key。仍建议使用密码管理器保存，并及时删除不再使用的密钥。
编辑 API Key¶
在密钥列表点击编辑（铅笔图标），可调整以下内容，密钥本身不会变化，已有调用方无需改配置：
- 名称：仅用于识别。
- 过期方式：在永不过期与自定义到期时间之间切换；也可修改已有的到期日期。到期时间必须晚于当前时间。
- IP 白名单：逐条添加单个 IP 或 CIDR 网段（如
203.0.113.10、203.0.113.0/24），可随时移除。留空表示不限制来源 IP。
IP 白名单为会员能力
免费用户不开放 IP 白名单。会员在编辑时若权益仍在有效期内，可正常增删规则；会员到期后仅能修改名称与到期时间，新增规则会被拒绝。
编辑不能修改读取权限、指数范围与调用额度；这些由账号权益决定。
接口文档入口¶
创建完 Key 后即可在页面上的「接口文档」卡片直接进入文档，无需回到顶部导航：
| 入口 | 路径 | 适合场景 |
|---|---|---|
| 用户手册 | /handbook/ |
阅读鉴权、分页、限流等使用约定与完整示例 |
Key 的限制项¶
| 限制项 | 说明 |
|---|---|
| Key 数量 | 免费用户 1 个；专业会员不限 |
| 读取权限 | 新 Key 默认具备全部公开数据集读取权限，不可单独裁剪 |
| 有效期 | 默认长期有效；可在编辑中调整到期时间，到期后自动失效（401 / 40103） |
| 调用频率 | 免费用户 10 次/分钟；专业会员 10000 次/分钟 |
| 每日调用额度 | 免费用户 10 次/日；专业会员 10000 次/日，见 限流说明 |
| IP 白名单 | 免费用户不支持；专业会员支持，可在创建或编辑时配置 |
| 指数覆盖 | 免费用户 7 个公开指数；专业会员 8 个指数系列（含会员专享指数） |
删除 Key¶
- 在 Key 列表点击删除并确认，密钥记录会永久移除。
- 删除后使用该 Key 的请求返回 401。
- 删除不可恢复；需要继续使用就创建新 Key。
Key 状态与鉴权失败排查¶
| 现象 | 原因 |
|---|---|
| 401 无效 Key | Key 已删除 / 已过期 / 输入错误 |
| 403 权限不足 | 调用了 Key 未包含的数据集（如用仅含 index:read 的历史 Key 查 index_quote） |
| 403 指数未授权 | Key 的指数范围不含目标指数，或该指数为会员专享而当前无会员权益 |
| 403 IP 不允许 | 来源 IP 不在白名单 |
| 429 调用受限 | 触发服务端频率保护或每日调用额度 |
详细错误码见 错误码与限流。
管理员能对我做什么¶
- 管理员：查看并删除免费用户的 Key。
- 超级管理员：管理所有角色的 Key，并查看全局数据查询调用日志。
Key 的所有权属于用户本人，管理员无法查看明文（系统仅存哈希与加密密文，密文仅供本人再次查看）。