管理你的 API 密钥
你的 API 密钥位于控制台的 API & Webhooks 页面，需保存在服务端，测试时请使用单独的 sandbox 应用，并了解如何解决 401 和 403 错误。
API & Webhooks，范围限定于你当前选中的应用。每个应用一个密钥，密钥就是环境本身 - live 应用上没有单独的测试密钥。它是服务端密钥：绝不能出现在前端代码或应用安装包中。
你的 API 密钥位于控制台侧边栏的 API & Webhooks 页面，范围限定于你当前使用的应用。请像对待密码一样对待它 - 它代表该应用完整的 API 访问权限。
#查找你的密钥
- 登录 Business Console
前往 business.didit.me 并登录。
- 选择你的应用
在控制台顶部的下拉菜单中选择目标应用。每个应用都有自己的密钥。
- 打开 API & Webhooks
你的 API 密钥就在这里，与你的 webhook 目标地址及其签名密钥并列展示。
- Create API key 用于签发新密钥；密钥按应用区分。
- 密钥只在此处显示一次 - 请将其复制到你自己的密钥保管工具中。
- Rotate secret 会替换密钥内容，但不会改变密钥的名称。
- Last used 可以帮你在吊销前区分正在使用的密钥和已被遗忘的密钥。
#API 密钥和签名密钥是两回事
有必要明确说明，因为混淆两者会产生令人困惑的错误：
| 用途 | 作用范围 | |
|---|---|---|
| API 密钥 | 在 x-api-key 请求头中，对你发往 Didit 的调用进行身份验证 | 按应用区分 |
| Webhook 签名密钥 | 验证收到的 webhook 确实来自 Didit | 按目标地址区分 |
把签名密钥当作 API 密钥发送会产生 401 错误。用 API 密钥去校验 webhook 签名会导致签名不匹配。这两种情况都很常见。
你的 API 密钥是一项机密信息。绝不能将其放入前端代码、公开代码仓库或移动应用安装包中 - 只能保存在服务端。出现在已发布应用安装包中的密钥，就是攻击者能拿到的密钥。参见 API 身份验证。
#获取用于测试的密钥
不要用生产环境进行测试。请在 sandbox 模式下创建一个单独的应用 - sandbox 会话会模拟所有外部检查，永远不会计费，也不会接触真实用户数据。开发期间使用它的密钥，同时保留一个单独的 live 应用用于真实核验。
live 应用上不存在所谓的"测试密钥"。密钥本身就是环境，因此在你保存密钥的任何地方，都值得给密钥起一个清晰无歧义的名字。参见在 sandbox 中测试。
#轮换你的密钥
如果某个密钥可能已经泄露，请在同一个 API & Webhooks 页面重新生成它。重新生成会立即使旧密钥失效，因此请先在所有使用该密钥的地方更新，否则你的生产流量会在你点击按钮的那一刻起就开始失败。
按计划定期轮换密钥是良好实践。把它当作一次发布来规划，而不是随手一点。
#修复 401 和 403 错误
| 错误 | 原因 | 修复方式 |
|---|---|---|
401 | 密钥缺失、格式错误，或已被重新生成 | 从该应用的 API & Webhooks 页面复制当前密钥。检查是否混入多余的空格或引号，并确认没有误粘贴成签名密钥 |
403 | 密钥有效，但此调用不被允许 | 通常是用错了应用、在 live 密钥上使用了仅限 sandbox 的字段（或反之）、密钥缺少某项权限，或账户未启用某项功能 |
某个特定工作流上出现的 403，几乎总是意味着这个密钥所属的应用不是拥有该工作流的应用。请在控制台切换应用，并改用对应应用的密钥。完整说明参见API 错误及其含义。
#限制密钥的可用范围
如果你的需求是限制某个密钥能访问的数据类别 - 例如不希望某个服务能获取证件图片 - 这属于权限问题而非密钥设置问题，具体可用的选项取决于你的账户。请向支持团队咨询，而不要自行假设某个密钥不受限制或已经受限；这两种假设在相反的方向上都有风险。
#团队中谁能看到密钥
密钥的可见性取决于角色。Developer 角色可以访问 API 密钥；Reader 不可以。如果某位同事找不到这个页面，请先检查其角色，而不是当作 bug 上报。参见邀请团队成员并设置角色。
#每次调用都会被记录
API 密钥发起的请求会出现在 Audit Logs 中，归属于该应用而非某个具体的人 - 这正是为什么多个服务共用同一个密钥会让事故排查变得更困难。每个调用方使用独立的密钥更便于追溯。参见使用审计日志。