API Key 使用实践

功能概述

这一页不再解释 API Key 是什么，而是回答“怎样把 API Key 用得长期稳定”。
重点包括：

• 命名规范
• 授权边界
• 上线验证
• 轮换与回收
• 长期审计

适用场景

适合下面几类场景：

• 平台已经开始有多个集成系统
• 不同环境需要分开管理密钥
• 团队希望建立统一的安全规范

前置条件

开始前建议准备：

• 一份环境划分方案，例如开发、测试、生产
• 一份调用系统清单
• 一份密钥保管与轮换责任人清单

操作步骤

第 1 步：建立统一命名规则

推荐命名至少包含 3 类信息：

• 系统名称
• 环境
• 用途

例如：crm-prod-agent-call。
这样后续看日志、做轮换和查异常时成本最低。

第 2 步：每个环境单独发 Key

开发、测试、生产不要混用同一个 Key。
否则测试泄露、误调用生产或问题排查都会变得非常困难。

第 3 步：按最小权限发放

先从最窄权限开始，确有需要再逐步扩大。
尤其要避免一开始就授予：

• 全部 Agent 访问
• 全部工作流执行
• 全部资源管理权限

第 4 步：上线前做反向验证

除了验证“能不能调用成功”，还要验证：

• 调用未授权资源会不会被拒绝
• Key 停用后是否立刻失效
• 调用频率过高时是否有预期行为

第 5 步：建立轮换和回收机制

对于长期使用的 Key，建议提前定义：

• 到期前多久轮换
• 系统下线后由谁回收
• 异常泄露后如何紧急停用

结果验证

实践规范建立后，建议定期检查：

• 是否存在无人认领的 Key
• 是否存在长期未使用但仍有效的 Key
• 是否存在权限明显过宽的 Key
• 是否存在测试 Key 被用于生产系统

价值说明

这套实践的价值不在于“更复杂”，而在于：

• 密钥可识别、可替换、可停用
• 集成系统的责任边界更清晰
• 安全治理和排障成本更低

注意事项

• 不要把 Key 名称写得过于笼统，例如 test、api、system
• 密钥规范一旦建立，应对所有新系统统一执行
• 轮换演练要在真正故障前完成，而不是等泄露后再设计流程