管理你的 API 密钥

在控制台的开发者 → API 密钥下创建和轮换密钥：为每个服务分配独立权限，仅在服务端保存，并解决 401 和 403 错误。

你的 API 密钥位于控制台的开发者 → API 密钥下，范围限定于你当前使用的应用。请像对待密码一样对待每一个密钥：它代表该应用的 API 访问权限。

#查找你的密钥

1. 登录 Business Console

   前往 business.didit.me 并登录。

2. 选择你的应用

   在侧边栏顶部的应用卡片中选择应用。每个应用都有自己的密钥。

3. 打开开发者，然后打开 API 密钥

   密钥标签页列出所有密钥，最先列出的是主密钥，并显示每个密钥的访问权限、最近使用时间和过期时间。

#创建密钥

为每个调用 Didit 的服务分配独立的密钥，这样你就能看清每个服务在做什么，并单独吊销它。

1. 点击创建密钥

   在开发者 → API 密钥页面上。

2. 为密钥命名并选择环境

   以将要使用该密钥的服务为其命名，选择生产（真实核验，会计费）或沙盒（测试数据，从不计费；该密钥会创建在你组织的沙盒应用中），并选择过期时间：永不过期，30 天、90 天或一年后过期，或在你选定的日期过期。

3. 选择访问权限

   完全访问可读写所有内容，适用于你自己的后端。只读可查看会话、决策和媒体文件，但不能更改任何内容，适用于只需要结果的合作伙伴。自定义允许你逐个资源进行选择。如果该服务只需要决策结果，而不需要证件图片、自拍照、视频或 PDF 报告，请取消勾选包含媒体文件。

4. 检查并复制密文

   完整密文只在创建密钥时显示一次。请直接将其复制到你的密钥管理工具中。

主密钥是该应用最初的密文。它始终拥有完全访问权限，可以轮换，但不能吊销。

#API 密钥和签名密钥是两回事

有必要明确说明，因为混淆两者会产生令人困惑的错误：

把签名密钥当作 API 密钥发送会产生 401 错误。用 API 密钥去校验 webhook 签名会导致签名不匹配。这两种情况都很常见。

#获取用于测试的密钥

不要用生产环境进行测试。将控制台切换到沙盒并在那里创建密钥，或者在创建密钥时选择沙盒作为环境。sandbox 会话会模拟所有外部检查，永远不会计费，也不会接触真实用户数据。

一个密钥属于一个应用，也因此属于该应用的环境：sandbox 密钥永远不会创建 live 核验，live 密钥也永远不会创建 sandbox 核验。在你保存密钥的任何地方，都值得给密钥起一个清晰无歧义的名字。参见在 sandbox 中测试。

#轮换你的密钥

如果某个密钥可能已经泄露，请打开它并选择轮换密钥。你会得到一个新密文，而旧密文会继续有效 24 小时，因此你可以在不停机的情况下部署新密文。此后，所有使用旧密文的请求都会返回 401。

如果某个密钥必须立即停止工作，请改用吊销密钥。吊销会立即停用该密钥，且无法撤销。主密钥只能轮换。

按计划定期轮换密钥是良好实践。把它当作一次发布来规划，而不是随手一点。

#修复 401 和 403 错误

某个特定工作流上出现的 403，几乎总是意味着这个密钥所属的应用不是拥有该工作流的应用。请在控制台切换应用，并改用该应用的某个密钥。完整说明参见API 错误及其含义。

#限制密钥的可用范围

在创建密钥时选择访问权限，之后可以通过编辑访问权限进行更改（密文保持不变；主密钥的访问权限无法编辑）。只读可防止合作伙伴更改任何内容；自定义可为每种资源（会话、决策、媒体文件、用户、企业等）分别设置无、读取或写入；关闭包含媒体文件可防止某个服务下载证件图片、自拍照、视频和 PDF 报告。在限制下，还可以将密钥限定于部分工作流、仅限已通过的会话，或一组 IP 地址：来自列表之外的请求会返回 403，而超出该密钥工作流或状态范围的会话会返回 404。打开某个密钥即可准确查看它能做什么；密钥能做的事情永远不会超出其访问权限所允许的范围。

#团队中谁能看到密钥

密钥的可见性取决于角色：查看该页面需要读取 API 密钥的权限，开发者角色包含这一权限。密文在控制台中始终以遮蔽方式显示。如果某位同事找不到这个页面，请先检查其角色，而不是当作 bug 上报。参见邀请团队成员并设置角色。

#每次调用都会被记录

API 密钥发起的请求会出现在审计日志中，归属于该密钥而非某个具体的人。这正是为什么多个服务共用同一个密钥会让事故排查变得更困难：每个调用方使用独立的密钥更便于追溯。参见使用审计日志。