如何零停机轮换 UnifyPort API Key

要在不中断服务的情况下轮换 UnifyPort API Key，不要一开始就调用 rotate 接口。POST /v1/api-keys/{key_id}/rotate 成功后会立即让旧 Key 失效。正确顺序是：创建第二把有效 Key，安全保存只显示一次的新密钥，把它部署到所有调用方，用 GET /v1/workspace 验证，最后才把旧 Key 设为 inactive。

关键结论

• 专用 rotate 接口是即时切换，不提供旧 Key 的宽限期。
• 零停机替换需要短暂保留两把有效 Key，按“创建、部署、验证、停用”执行。
• 新建或轮换后的完整密钥只会在 data.api_key 中返回一次，之后无法重新读取。
• Key 列表只返回 key_prefix、状态等元数据，不返回完整密钥。
• 普通滚动发布使用“新建后停用”；只有需要立即撤销旧凭证时才使用 rotate。

为什么直接 rotate 可能造成生产中断

Rotate API key 文档定义了这个操作：

POST /v1/api-keys/{key_id}/rotate

它会创建一条新的 Key 记录，并只返回一次新密钥；与此同时，旧 Key 立即失效。如果旧凭证可能已经泄露，这种行为很有价值。但如果 Web 服务、队列 worker、定时任务和不同区域的实例仍在读取旧值，请求就可能变成 401 invalid_api_key。

滚动发布本来就存在新旧配置短暂并行的阶段。即时撤销旧凭证会消除这个重叠窗口，因此即使应用本身健康，也会出现认证失败。

NIST SP 800-53 的认证器管理控制包含更换或刷新认证器的一般要求，但实际操作顺序必须服从产品契约：UnifyPort 允许工作区存在多条 API Key 记录，而 rotate 会立即淘汰旧 Key。

零停机 API Key 轮换步骤

1. 先盘点所有调用方

列出所有向 https://api.unifyport.ai 发送 X-Api-Key 的组件：对外 API、后台 worker、会发起回复调用的 webhook 任务、定时作业、生产运维工具和健康检查。

不要把 API Key 和 webhook 的 signing_secret 混为一谈。API Key 用于认证你的 UnifyPort REST API 请求；signing_secret 用于验证发往你接收端的 webhook。后者可参考Webhook HMAC、重放防护与重试指南。

先通过 List API keys 查看记录：

curl https://api.unifyport.ai/v1/api-keys \
  -H "X-Api-Key: $CURRENT_UNIFYPORT_API_KEY"

响应会提供 id、name、key_prefix 和 status，但不会暴露完整密钥。

2. 创建第二把有效 Key

不要调用 rotate，而是使用 Create API key：

curl -X POST https://api.unifyport.ai/v1/api-keys \
  -H "X-Api-Key: $CURRENT_UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production 2026-08 cutover",
    "prefix": "dk_live"
  }'

成功的 201 响应在 data.key 中返回元数据，在 data.api_key 中返回一次完整新密钥。应直接把它写入团队批准的密钥管理系统，不要打印到部署日志，也不要粘贴到工单或聊天中。

如果部署前丢失了这次性值，应重新创建一把 Key，并停用未使用的记录；不能根据前缀恢复密钥。

3. 在部署前证明新 Key 可用

用新密钥执行只读认证检查：

curl https://api.unifyport.ai/v1/workspace \
  -H "X-Api-Key: $NEW_UNIFYPORT_API_KEY"

成功响应说明新 Key 能解析到当前工作区，但不代表所有应用实例都已经加载它。接下来更新部署使用的密钥引用，并逐批发布到每类调用方；在此期间保持旧 Key 为 active。

记录发布版本、实例组和负责人即可，不要记录任何密钥值。对面向东南亚运营的中国团队，还要特别检查跨区域 worker、夜间定时任务和临时客服工具，避免只更新主站服务。

4. 验证整个调用集群

停用旧 Key 前逐项确认：

• Web 与 API 实例已完成发布；
• 队列消费者已经重启或重新加载配置；
• 定时任务下次运行会读取新密钥；
• 消息回复或发送路径能完成已认证请求；
• 没有应急脚本依赖复制到本地的旧值。

这个阶段应依据应用侧请求结果和部署状态。UnifyPort 的 Key 列表只记录元数据和状态，并未文档化“每把 Key 最后使用时间”等分析字段，因此不要从不存在的数据推断已经完成迁移。

如果团队主要通过控制台起步，可先阅读控制台与 API Key 管理公告。本文补充的是在线系统真正需要的发布顺序。

5. 停用旧 Key

确认所有调用方都使用新密钥后，用新 Key 调用 Update API key status：

curl -X PATCH "https://api.unifyport.ai/v1/api-keys/$OLD_KEY_ID" \
  -H "X-Api-Key: $NEW_UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"inactive"}'

文档支持的状态是 active 和 inactive。停用后，用旧密钥做一次受控的只读请求，确认返回 401 invalid_api_key；不要用真实业务任务做这个检查。

最后，从部署配置、本地环境文件、CI 变量和临时迁移材料中删除旧值。运维记录只保留 Key ID、名称、状态、负责人和切换时间等非敏感信息。

什么时候应该使用即时 rotate

当“旧凭证必须立刻失效”本身就是目标时，才使用 POST /v1/api-keys/{key_id}/rotate，例如怀疑凭证泄露，或所有调用方都能在维护窗口内同步切换。

此时顺序不同：

1. 暂停或隔离仍持有旧 Key 的调用方；
2. 从受控运维路径调用 rotate；
3. 只捕获一次 data.api_key；
4. 更新所有密钥使用方；
5. 恢复流量并验证认证。

这条路径优先保证撤销速度，而不是连续可用性。如果存在泄露风险，不应为了维持流量而人为延长双 Key 并行时间，应遵循团队的安全事件流程。

限制与取舍

短暂的双 Key 阶段意味着两份有效凭证都能访问工作区。应尽量缩短窗口，并限制能够读取密钥的人员和系统。UnifyPort 文档说明 X-Api-Key 会解析到一个工作区并授予该工作区内的访问能力，因此这不是按单个 endpoint 拆分权限的迁移。

本流程也不会轮换 webhook signing_secret、渠道登录材料或导入会话。不同密钥类型有不同消费者和故障模式，应分别变更和验证。

FAQ

UnifyPort API Key 轮换有宽限期吗？

文档化的 rotate 接口没有宽限期，成功后旧 Key 立即失效。需要重叠窗口时，应先创建第二把 Key。

新 API Key 以后还能重新读取吗？

不能。完整值只在创建或轮换响应的 data.api_key 中出现一次，之后列表仅显示前缀和状态等元数据。

如何安全测试新 Key？

使用新的 X-Api-Key 调用 GET /v1/workspace，然后确认每一类已部署调用方都加载了同一新密钥，再停用旧记录。

rotate 和“创建后停用”应该选哪个？

普通滚动发布选择“创建后停用”；需要立即撤销旧凭证且已经隔离旧调用方时选择 rotate。

API Key 与 signing_secret 是同一个密钥吗？

不是。X-Api-Key 认证 REST API 请求，signing_secret 用于验证 webhook 的 HMAC-SHA256 签名。

下一步

打开 Create API key 参考，创建并行生产凭证，在修改旧 Key 状态前完成以上五个检查点。

来源

核对日期：2026 年 8 月 17 日。

• UnifyPort：Create API key
• UnifyPort：List API keys
• UnifyPort：Update API key status
• UnifyPort：Rotate API key
• NIST SP 800-53 Revision 5