API Key 与轮换

一把 Key 两个值、轮换有重叠窗口、生产环境必配 IP 白名单 —— 三件事各有一个容易踩的坑。

创建时我方一次性下发两个值：

值	用途	我方存的是	丢了怎么办
`api_key`	换令牌（`POST /v1/connect/token`）	只有哈希	只能重发一把新的
`signing_key`	请求验签	明文（对称算法要求）	可以取回

⚠ 这两个值不可互换。拿 signing_key 去换令牌会得到 401，

而那个 401 与「Key 过期了」长得一模一样 —— 排查时先确认拿的是哪一个。

轮换不是「立刻作废旧的」。我方保留旧 Key 一段重叠窗口：


       轮换
        │
旧 Key  ├────────────┤          ← 窗口内仍然可用
新 Key  ├──────────────────────►
        └── 重叠窗口 ──┘

为什么需要它：你的服务是多实例的，配置不会在同一毫秒生效。没有重叠窗口的话，轮换那一刻总有几个实例还拿着旧 Key 在打 —— 表现是一阵 401，而它看起来像我方出了故障。

窗口结束后旧 Key 立刻失效，不再有第二次宽限。

API Key 不区分 sandbox/live。请在对应环境的商户后台创建 Key：

merchant.zinfra.dev / api.zinfra.dev：测试（沙盒）环境，不要求也不校验 IP 白名单。
merchant.zinfra.vip / api.zinfra.vip：生产环境，创建 Key 需安全验证，IP 白名单必须非空；只有名单内的来源 IP 可以调用接口。

两套环境的数据与凭据分别存储。切换环境时，使用目标环境创建的凭据。新建及轮换的密钥不再带 live / test 前缀；已有密钥无需因前缀更名而重建。