# 管理你的 API 密钥

Source: https://help.didit.me/zh/account-organization/api-keys
Updated: 2026-10-12

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

**开发者 → API 密钥**，范围限定于你当前选中的应用。每个应用都有一个**主密钥**，
你还可以创建更多密钥，每个服务一个，各自拥有独立的访问权限和过期时间。密钥是
服务端机密：绝不能出现在前端代码或应用安装包中。

[Video: 设置 API 密钥并测试您的 Webhook - Didit Academy](https://www.youtube.com/watch?v=thOMIGbNLP0&t=38)

[Video: 5 步完成 KYC API 集成，附 Cursor 的 AI 配置提示词 - Didit Academy](https://www.youtube.com/watch?v=kTAarcImy7E)

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

## 查找你的密钥

1. **登录 Business Console**

   前往 [business.didit.me](https://business.didit.me) 并登录。

2. **选择你的应用**

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

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

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

![Didit 控制台中的 API 密钥页面，显示密钥列表](https://help.didit.me/screenshots/api-keys-light.webp)

*该应用的所有密钥：最先是主密钥，然后是你创建的密钥。*

## 创建密钥

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

1. **点击创建密钥**

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

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

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

3. **选择访问权限**

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

4. **检查并复制密文**

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

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

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

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

| | 用途 | 作用范围 |
|---|---|---|
| **API 密钥** | 在 `x-api-key` 请求头中，对你发往 Didit 的调用进行身份验证 | 按应用区分，数量按需创建 |
| **Webhook 签名密钥** | 验证收到的 webhook 确实来自 Didit | 按 webhook **端点**区分 |

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

> **Warning:** 你的 API 密钥是一项机密信息。绝不能将其放入前端代码、公开代码仓库或移动应用安装包中 -
> 只能保存在服务端。出现在已发布应用安装包中的密钥，就是攻击者能拿到的密钥。参见
> [API 身份验证](https://docs.didit.me/getting-started/api-authentication)。

## 获取用于测试的密钥

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

一个密钥属于一个应用，也因此属于该应用的环境：sandbox 密钥永远不会创建 live 核验，live 密钥也永远不会创建 sandbox 核验。在你保存密钥的任何地方，都值得给密钥起一个清晰无歧义的名字。参见[在 sandbox 中测试](https://help.didit.me/zh/getting-started/sandbox-and-testing)。

## 轮换你的密钥

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

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

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

## 修复 401 和 403 错误

| 错误 | 原因 | 修复方式 |
|---|---|---|
| `401` | 密钥缺失、格式错误、已过期、已吊销，或轮换已超过 24 小时 | 在该应用的**开发者 → API 密钥**下检查该密钥。检查是否混入多余的空格或引号，并确认没有误粘贴成签名密钥 |
| `403` | 密钥有效，但此调用不被允许 | 通常是用错了应用、在 live 密钥上使用了仅限 sandbox 的字段（或反之）、使用了该密钥未被授予的访问权限（例如只读密钥尝试写入），或账户未启用某项功能 |

某个特定工作流上出现的 `403`，几乎总是意味着这个密钥所属的应用**不是**拥有该工作流的应用。请在控制台切换应用，并改用该应用的某个密钥。完整说明参见[API 错误及其含义](https://help.didit.me/zh/integration/api-errors)。

## 限制密钥的可用范围

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

## 团队中谁能看到密钥

密钥的可见性取决于角色：查看该页面需要读取 API 密钥的权限，**开发者**角色包含这一权限。密文在控制台中始终以遮蔽方式显示。如果某位同事找不到这个页面，请先检查其角色，而不是当作 bug 上报。参见[邀请团队成员并设置角色](https://help.didit.me/zh/account-organization/team-members-and-roles)。

## 每次调用都会被记录

API 密钥发起的请求会出现在**审计日志**中，归属于该密钥而非某个具体的人。这正是为什么多个服务共用同一个密钥会让事故排查变得更困难：每个调用方使用独立的密钥更便于追溯。参见[使用审计日志](https://help.didit.me/zh/account-organization/audit-logs)。