深色模式
认证与密钥
开放 API 用 API Key 认证，不用账号密码。一个 Key 对应一个调用方，权限与数据范围跟着 Key 走。
一、建一个 Key
- 用平台管理员账号登录后台，进「开放 API」菜单
- 点新建，填名称（如「BI 报表」）、数据归属范围、配额与有效期
- 保存后完整密钥只显示这一次，复制走妥善保存
完整密钥以 uak_ 开头，中间一段是密钥编号，后一段是密钥内容，两段用下划线分隔。后台只保留密钥的摘要与加密存储，之后想看只能走「回显」动作并留下记录，所以新建时就要存好。
二、请求头
http
GET /api/open/v1/tickets?page=1&page_size=20 HTTP/1.1
Host: jinxino.cn
X-API-Key: uak_xxxxxxxx_yyyyyyyyyyyyyyyy也支持用标准的 Authorization: Bearer <密钥>，两种写法等价，同一个请求只带一种。
密钥要放在服务端，不要写进前端页面、小程序或公开仓库。怀疑泄露立刻停用并换新 Key。
三、Key 上的四项设置
| 设置 | 作用 |
|---|---|
| 名称 | 用来区分调用方，建议一个系统一个 Key |
| 数据归属范围 | 决定能读到哪个客户的数据，跨范围返回不存在 |
| 能力域 | open 为只读查询；未开 open 的 Key 调接口返回 403 |
| 每分钟配额 | 该 Key 的调用上限，留空按平台默认值 |
| 有效期 | 到期自动失效，适合给外包或临时项目用 |
一个系统一个 Key 的好处是：出问题能定位到具体调用方，停用也只影响这一个系统。
四、轮换与停用
| 动作 | 场景 | 做法 |
|---|---|---|
| 轮换 | 定期更换密钥 | 生成新密钥，调用方切过去，确认无流量后停用旧 Key |
| 停用 | 系统下线或密钥泄露 | 立即停用，接口返回 403 |
| 删除 | 确认不再使用 | 删除后调用日志仍保留，便于事后追溯 |
轮换不要直接覆盖：先并行一段时间，确认新 Key 稳定后再停旧的，避免切的过程中断数据。
五、调用日志
「开放 API」菜单里能看两类数据：
- 调用日志：每次调用的时间、Key、端点、状态码与耗时
- 调用统计：按 Key 聚合的次数、错误数、平均耗时与状态码分布
排查「数据为什么没更新」时先看日志：没有调用记录说明对方的定时任务没跑，有记录但状态码是 4xx 说明请求本身有问题。
常见问题
密钥丢了怎么办？ 轮换一个新 Key，停用旧的。没法找回原密钥。
能用同一个 Key 给多个系统吗？ 技术上可以，但不建议。分开建 Key 才能分别统计与停用。
Key 会过期吗？ 建的时候可以设有效期，不设就长期有效。给外部合作方用的建议设有效期。