API Key 与账号认证

API Key 接入

自动采集使用平台管理员交付的 BI 专用 API Key。所属账号仅授予 bi_reader，每个 Key 均可独立撤销、轮换与设置有效期；默认 90 天，可设 1–365 天。明文仅生成时展示一次，遗失后撤销重建。凭据通过独立安全渠道交付，不放入文档、压缩包、源码、日志或 URL。

请求头携带 X-API-Key: <运行时从安全存储读取的 Key>，无需登录，也不需要刷新令牌。此凭据仅允许 GET 查询 payments、payment-orders、payment-events、usage、calls 五个 BI 数据接口。账号、任务、支付操作、Key 管理和改密接口不可使用此 Key。可选的 X-Request-Id 应为 UUID，否则服务器重新生成；排查时使用响应返回的请求编号。一次请求只能选择 Key 或 Bearer，不能混用、重复发送 Key 头。

账号停用、失去 BI 角色、Key 到期或撤销后，新的请求立即拒绝，包括缓存命中；已经完成鉴权的在途读取可能继续完成。账号改密、密码重置不撤销独立 Key。轮换立即撤销旧 Key，新 Key 默认 90 天；采集程序更新安全存储后恢复。

401 表示 Key 无效或已停用，停止采集并联系平台管理员；不重新登录或回退到另一种凭据。限流默认每个账号每分钟 60 次；同一账号所有 Key 与密码方式共享额度，新增 Key 不增加额度。

平台按证明持有 Key 的请求记录调用时间、接口、状态码、耗时、请求编号和错误码，包括参数错误、限流、越权、已撤销或到期后的拒绝。伪造或混用凭据的请求记入通用服务日志，不归入某个真实 Key。越权访问非 BI 数据路径归为 unmatched，不保存任意路径文本、查询参数、请求正文或返回业务数据。明细保留 90 天，累计调用数持续保留。审计存储故障返回 503 / BI_AUDIT_UNAVAILABLE，禁止返回未经记录的成功结果；这类请求可能没有明细，平台通过独立故障指标和请求日志排查。

兼容账号认证

平台管理员创建账号时仅选择 bi_reader。角色不可与其他管理角色组合。用户名和临时密码经独立安全渠道交付，密码不写入文档、代码、压缩包、日志或 URL。

1. POST /api/v1/bi/auth/login，JSON 为 {"username":"账号名","password":"账号密码"}。
2. 返回 access_token、token_type、expires_in 和 must_change_password。令牌有效时长以 expires_in 为准，默认 28800 秒。
3. 首次登录若 must_change_password=true，先调用 POST /api/v1/bi/auth/change-password，请求头携带 Authorization: Bearer <token>，JSON 包含 current_password、new_password。新密码至少 14 个字符、不包含用户名，至少 8 种不同字符，且不可与旧密码相同。
4. 修改成功返回 204，旧令牌立即失效。使用新密码重新登录，再开始取数。GET /api/v1/bi/auth/session 可检查当前认证与是否需要改密。
5. 后续只读请求携带 Authorization: Bearer <token>。令牌到期重新登录，本认证链路没有 refresh token 接口。

账号停用、权限调整、密码重置和改密会使旧会话失效。每次读取，包括缓存命中，均先检查认证与权限。不要通过循环登录绕过拒绝；401 最多重新登录一次，403 应按错误码处理。

兼容采集任务从受限密码文件或所属部署环境的 Secret 存储读取密码；令牌保存在进程内存，不写入导出数据。通过 HTTPS 访问生产，不使用浏览器保存管理员登录态作为 BI 服务凭据。

平台默认对同一账号限制每分钟 60 次数据查询；登录另有限流。遵守返回的 Retry-After。多个采集进程共享同一账号时共同消耗该账号的查询额度。