> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# API 密钥权限范围 - Didit 受限 KYC API 访问控制

> 为每个服务或合作方分配独立的 API 密钥，仅授予所需权限：按资源设置读写权限、工作流限制、IP 白名单、到期时间及即时撤销。Didit 支持。



限定范围的 API 密钥提示词
        将提示词复制到剪贴板



      
      

\<pre>

\````# Goal - call Didit with a scoped API key

Every application has a primary secret with full access, and any number of named API keys.
A named key carries its own access: read or write per resource, optional limits, an optional IP allowlist and an optional expiry date.
Keys are created, edited, rotated and revoked in the Business Console (Developers -> API keys); there is no API to manage them.

\## Sending the key

\```bash
curl https://verification.didit.me/v3/session/$SESSION_ID/decision/ \
-H "x-api-key: $DIDIT_API_KEY"
\```

Read the key from an environment variable or a secrets manager, never from source code.

\## What each answer means

\| Status | Meaning |
\|---|---|
\| 401 | The key is missing, wrong, revoked or expired |
\| 403 | The key has no access to this resource or action, or the request came from an address outside its IP list |
\| 404 | The session is outside the key's workflows or statuses, so to this key it does not exist |

A key without media access receives decisions with every image, video and PDF URL set to null, and gets 403 on PDF reports.
A key without sessions write receives session_url and session_token as null.

\## Resources

sessions, decisions, media (read only), users, businesses, transactions, workflows, webhooks, applications, analytics (read only), api-keys.
Read covers GET requests, write covers POST, PUT, PATCH and DELETE.
Standalone checks (face match, ID verification, AML screening and the other /v3 standalone APIs) need sessions write.
Creating a person with send_verification_link: true (POST /v3/users/create/) needs users write and sessions write; without sessions write it answers 403 and nothing is created.

\## Limits

\- workflow_ids: only sessions of these workflows are visible, and sessions can only be created with them.
\- approved sessions only: declined, in-review and unfinished sessions are hidden.
\- A key with either limit cannot have access to users, businesses, transactions or analytics.

\## Rotation

Rotating a key returns a new secret once; the previous secret keeps working for 24 hours.````

\</pre>



      
      

粘贴到

每个应用都从一个拥有该应用全部功能完整访问权限的**主密钥**开始。
你可以在它旁边添加**具名 API 密钥**，每个服务或合作方一个，每个密钥只拥有其所需的访问权限。
例如，可以为出款服务商提供一个密钥，使其只能读取某个工作流中已通过的会话，且无法做任何更改；为后端保留另一个单独的密钥；并且可以撤销其中任何一个，而不影响另一个。> [!NOTE]
>
> 在引入限定访问权限之前创建的密钥保留完整访问权限。
> 在你编辑其访问权限之前，它们不会有任何变化。***## 在哪里找到它们在[**业务控制台**](https://business.didit.me)中选择你的应用，然后打开 **Developers -> API keys**。列表显示应用的每个密钥，包括其状态、过去 30 天的请求数、创建者、访问权限以及最近一次使用时间。
点击某个密钥可在右侧预览，或打开其完整页面，查看用量、访问权限、近期请求、快速入门代码片段及其活动记录。密钥只属于一个应用，且仅对该应用有效。
密钥继承应用的环境：沙盒应用的密钥永远不会产生计费验证。***## 重定向 URL 与允许的域名打开 **Developers > API keys > Redirects and domains**，为所选应用和环境设置两个列表。| 列表 | 控制内容 |
| - | - |
| **重定向 URL** | 托管验证结束后，Didit 将浏览器跳转到的地址。URL 必须完全匹配，包括路径。 |
| **允许的域名** | 托管验证流程可嵌入其中，并可将用户重定向回其中的来源（协议、主机及可选端口，例如 `https://app.example.com`）。 |当 **允许的域名** 列表中有条目时，[创建会话](https://docs.didit.me/zh/sessions-api/create-session.md)会以 `400` 错误拒绝不在其中任何一个域名上的 `callback`。
列表为空表示不做任何限制。
服务器到服务器的调用不受影响。***## 创建密钥**1. 详情**以将使用该密钥的服务为其命名，并选择过期时间：永不过期、30 天、90 天、一年，或您指定的日期。
密钥过期后，将于当天 UTC 时间结束时失效。**2. 访问权限**先选择一个预设，再按资源进行细化设置。
该密钥的权限永远不会超出此范围。**3. 检查**在您把密钥交给他人之前，控制台会明确列出该密钥能做什么、不能做什么。**4. 机密值**复制机密值并保存到您的密钥管理器中。
完整机密值只会显示这一次。
如果丢失，请轮换该密钥以获取新密钥。### 预设| 预设 | 访问权限 |
| - | - |
| **完全访问** | 对所有资源都具有读取和写入权限，包括其他 API 密钥。适用于您自己的后端。 |
| **只读** | 会话和决策，可选择包含媒体文件。无法创建、修改或删除任何内容。适用于需要获取结果的合作方。 |
| **自定义** | 您可以为每个资源选择无、读取或写入。 |### 资源读取权限涵盖对某个资源的 `GET` 请求；写入权限还涵盖 `POST`、`PUT`、`PATCH` 和 `DELETE`。| 资源 | 读取 | 写入 |
| - | - | - |
| **会话** | 列出并打开会话 | 创建、更新和删除会话，导入会话，并运行独立检查（人脸比对、身份证件验证、AML 筛查以及其他独立 API） |
| **决策** | 结果、风险分数、提取的数据以及 AML 筛查历史 | 批准、拒绝或转入审核，并修改功能和 AML 命中状态 |
| **媒体文件** | 证件图像、自拍照、视频以及 PDF 报告 | - |
| **用户**（`users`） | 终端用户及其所有已验证信息 | 创建、更新和删除用户及其监控。使用验证链接创建用户还需要**会话**写入权限 |
| **公司**（`businesses`） | 企业档案、其证件和所有者 | 创建、更新和删除企业及其监控 |
| **交易** | 交易、警报、规则、监控事件、Travel Rule 数据以及钱包筛查 | 发送交易和事件，更改其状态，并管理 Travel Rule 设置、钱包地址簿和转账 |
| **工作流** | 工作流、问卷、名单和黑名单 | 创建和编辑这些内容 |
| **Webhook** | endpoint，以及投递记录（需要**决策**读取权限，因为每次投递都包含其发送的会话 payload） | 添加、编辑和删除 endpoint，并重新发送投递 |
| **应用设置**（`applications`） | 定制设置和余额 | 更改定制设置，并为余额充值 |
| **分析** | 指标和报告导出 | - |
| **API 密钥** | 保留用于密钥管理 | 保留用于密钥管理 |带有自定义访问权限的密钥可以访问公共 API：会话、用户、企业、交易、工作流和 Webhook endpoint，以及独立检查。
仅供 Business Console 使用的 endpoint 会向该密钥返回 `403`；这些 endpoint 需要完全访问权限的密钥。如果密钥没有**媒体文件**读取权限，它收到的会话决策中，每个图像、视频和 PDF 的 URL 都会被设为 `null`，而 PDF 报告 endpoint 会返回 `403`。
如果密钥没有**会话**写入权限，它永远不会收到会话的验证链接或会话 token，因为持有者可以代表终端用户完成验证。这些字段会返回 `null`。
同理，使用 `send_verification_link: true` 创建用户时，除了**用户**写入权限外，还需要**会话**写入权限，因为该操作会创建会话并通过邮件发送其链接。
如果没有该权限，调用会返回 `403`，且不会创建任何内容。### 限制| 限制 | 作用 |
| - | - |
| **工作流** | 该密钥只能看到您所选工作流的会话，并且只能使用这些工作流创建会话。任何其他会话都会返回 `404`，如同该会话不存在。 |
| **仅限已通过的会话** | 已拒绝、审核中和未完成的会话对该密钥保持隐藏。 |
| **IP 地址** | 该密钥只能从您列出的地址或 CIDR 范围访问（最多 20 个，IPv4 或 IPv6）。来自其他地址的请求会返回 `403`。 |
| **过期时间** | 过期后，使用该密钥的每个请求都会返回 `401`。 |限制为部分工作流或仅已通过会话的密钥，可以在可应用限制的会话 endpoint 上使用。
它无法访问用户、公司、交易或分析，也无法运行独立检查。***## API 如何响应受限密钥| 状态 | 含义 |
| - | - |
| **401** | 密钥缺失、错误、已被撤销或已过期。 |
| **403** | 该密钥无权访问此资源或执行此操作，或请求来自其 IP 列表之外的地址。 |
| **404** | 该会话不在密钥的工作流或状态范围内。 |会话列表只返回密钥的限制允许的会话。***## 编辑访问权限打开密钥的菜单、预览或页面，然后选择**编辑访问权限**。
更改预设、资源、限制或过期时间，然后在提交前仅检查发生变化的内容，包括变更前和变更后的对比。
密钥的机密值保持不变，因此无需重新部署，新的访问权限会在一分钟内生效。主机密值始终拥有完全访问权限，且无法编辑。***## 轮换密钥轮换会替换密钥的机密值。
新的机密值只显示一次，当前机密值会继续有效 **24 小时**，以便您在不中断服务的情况下部署新的机密值。
之后，使用旧机密值的每个请求都会返回 `401`。主机密值的轮换方式相同，同样有 24 小时的重叠期。***## 撤销密钥撤销会立即停止密钥：使用该密钥的每个请求都会返回 `401`。
此操作无法撤销。
主机密值无法撤销；请改为轮换它。***## 使用情况和审计跟踪每个密钥都会显示过去 30 天的请求、错误率和延迟，以及其最近的请求及状态码，包括被其限制拒绝的请求。每次使用 API 密钥进行的调用都会出现在组织的[审计日志](https://docs.didit.me/zh/console/audit-logs.md)中，并标明进行该调用的密钥名称。***## 谁可以管理密钥管理 API 密钥需要 **API 密钥**权限：读取权限可查看密钥，写入权限可创建、编辑、轮换和撤销密钥。
请参阅[角色与权限](https://docs.didit.me/zh/console/roles-permissions.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.