> ## 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 认证：安全发起 KYC API 请求

> 使用 x-api-key 请求头中的作用域密钥验证 Didit API 请求。密钥错误或已过期将返回 401，缺少密钥则返回 403。



API 身份验证提示词
        将提示词复制到剪贴板



      
      

\<pre>

\````# Goal — authenticate against Didit's REST API

Two hosts, two auth schemes. Never mix them up.

\## Host map

\| Host | Surface | Auth header |
\|---|---|---|
\| `https://verification.didit.me` | Verification API — sessions, workflows, entities, transactions, standalone APIs, lists, webhooks, billing (every `/v3/...` route) | `x-api-key: <DIDIT_API_KEY>` |
\| `https://apx.didit.me` | Account / organization / application management (`/auth/v2/programmatic/...`, `/auth/v2/organizations/...`) | `Authorization: Bearer <JWT access_token>` |

The verification API does **not** use OAuth Bearer tokens. It uses a long-lived API key on the `x-api-key` header. Treat the key as a server-side secret — never ship it to a browser or mobile bundle.

\## How to obtain the api_key (no console UI needed)

\<Warning>
Substitute `you@yourdomain.com` below with a real inbox. The register endpoint sends the verification code synchronously, so reserved test domains (`@example.com`, `@example.org`, `@*.test`, `@*.example`, `@*.invalid`) get refused by mail delivery and the call returns a `500`.
\</Warning>

\```bash
\# 1) Register — emails a 6-char code (15 min TTL).
\#    Password rules: ≥8 chars, 1 uppercase, 1 lowercase, 1 digit, 1 special.
curl -X POST https://apx.didit.me/auth/v2/programmatic/register/ \
-H "Content-Type: application/json" \
-d '{"email": "you@yourdomain.com", "password": "StrongP@ss1"}'

\# 2) Verify email — returns api_key inline.
curl -X POST https://apx.didit.me/auth/v2/programmatic/verify-email/ \
-H "Content-Type: application/json" \
-d '{"email": "you@yourdomain.com", "code": "A3K9F2"}'
\# 200 -> { access_token, refresh_token, organization, application: { api_key, client_id, uuid } }
\```

Persist `response.application.api_key` as the env var `DIDIT_API_KEY`.
New keys start with `sk_live_` (live application) or `sk_test_` (sandbox application), followed by 43 URL-safe characters.
Keys created before this format have no prefix and keep working, so never validate a key by its prefix.

\## Recover the key (lost it)

\```bash
\# Log back in to get a fresh JWT
TOK=$(curl -s -X POST https://apx.didit.me/auth/v2/programmatic/login/ \
-H "Content-Type: application/json" \
-d '{"email":"you@yourdomain.com","password":"StrongP@ss1"}' | jq -r .access_token)

\# Find your org and app
curl https://apx.didit.me/auth/v2/organizations/me/ -H "Authorization: Bearer $TOK"
curl https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/$APP_ID/ \
-H "Authorization: Bearer $TOK"
\# Response.api_key is your key.
\```

\## Calling the verification API

\```bash
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"workflow_id":"<WORKFLOW_ID>","vendor_data":"user-42","callback":"https://myapp.com/return"}'
\```

\## Failure modes

\| Status | Meaning | Fix |
\|---|---|---|
\| `401` on verification.didit.me | `x-api-key` header wrong, malformed, revoked or expired | Re-fetch via the recover-key flow above, or use a key that has not expired |
\| `403` on verification.didit.me | No `x-api-key` header, a scoped key without access to this resource or action, or a key called from an address outside its IP list | Use a key with that access (Developers -> API keys in the console) |
\| `403` with `"code": "application_deleted"` on verification.didit.me | The key's application was deleted. You get this for a few minutes after the deletion; after that the key is refused like any invalid key | Do not retry: the application and its keys no longer exist. Use a key of an application that exists |
\| `404` on a session route | The session is outside the scoped key's workflows or statuses | Use a key whose limits include that session |
\| `403` on apx.didit.me | JWT `Authorization` header missing or expired | Call `POST /auth/v2/programmatic/login/` again |
\| `429` | Rate limit; response includes a `wait` field (seconds) | Back off, then retry |

\## Sources of truth
\- /openapi-auth.json — every account / org / app endpoint
\- /openapi-25.json — every verification endpoint
\- /integration/integration-prompt — end-to-end integration recipe````

\</pre>



      
      

粘贴到

## 获取您的 API 密钥在 Didit 中，API 密钥的作用域限定在您账户中的特定**应用**。应用是一个工作空间，您可以在其中为特定项目或环境配置工作流并管理验证。创建应用时，每个应用都会获得一个具有完整访问权限的主要 API 密钥。您还可以在其旁边添加更多密钥，每个密钥仅授予特定服务或合作伙伴所需的访问权限。要查找您的密钥：**1. 登录 Business Console**前往 [**Didit Business Console**](https://business.didit.me) 并登录。**2. 选择您的应用**从顶部的下拉菜单中选择您要使用的**应用**。**3. 打开 API 密钥**在左侧边栏中导航至 **开发者 -> API 密钥**。**4. 复制或创建密钥****主要**密钥是该应用自身的密钥。创建新密钥可为服务或合作伙伴提供其独立的机密，并授予其所需的访问权限。> [!WARNING]
>
> **您的 API 密钥属于机密信息，请像对待密码一样妥善保管。**
>
> 主要密钥可代表您的应用提供对 API 的完全访问权限。切勿将其暴露在前端代码、公开代码仓库或客户端打包产物中。请始终仅将其保存在服务端。### API 密钥格式生产环境应用的新 API 密钥以 `sk_live_` 开头，沙盒应用的新 API 密钥以 `sk_test_` 开头，后跟 43 个 URL 安全字符（字母、数字、`-` 和 `_`）。
在此格式推出之前创建的密钥没有前缀，将继续有效且无需更改。
请在 `x-api-key` 请求头中发送完整的密钥（包括前缀），并且不要因为密钥没有前缀而将其拒绝。## 获取您的组织 ID您的**组织 ID**是用于标识您组织的 UUID。您可以在限定组织范围的 API 路径中使用它，例如 `/auth/v2/organizations/me/{org_id}/applications/`。您可以直接从 Business Console 复制它，无需调用 API：**1. 打开组织设置**在 [**Didit Business Console**](https://business.didit.me) 中，前往**组织设置**。**2. 复制组织 ID****组织 ID** 字段会在组织名称旁显示您组织的 UUID，并配有复制到剪贴板按钮。***## 发起经过身份验证的请求如需对 API 请求进行身份验证，请在 `x-api-key` HTTP 请求头中包含您的机密 API 密钥。以下是对 `Create Session` endpoint 发起经过身份验证的请求的示例：```shell cURL theme={null}
curl --request POST \
     --url https://verification.didit.me/v3/session/ \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: YOUR_API_KEY' \
     --data '
{
  "workflow_id": "WORKFLOW_ID",
  "vendor_data": "USER_ID",
  "callback": "CALLBACK_URL"
}
'
```***## 错误处理如果您的 API 密钥错误、格式有误或已被撤销，API 将返回 `401 Unauthorized`：```json theme={null}
{
  "detail": "Authentication credentials were not provided or are invalid."
}
```已过期的密钥也会返回 `401`，且带有 `"detail": "This API key has expired."`。
未携带密钥的请求将返回 `403`，且带有 `"detail": "You do not have permission to perform this action."`。| 状态码 | 含义 |
| - | - |
| **401** | API 密钥错误、格式有误、已被撤销或已过期 |
| **403** | 未发送 API 密钥、该密钥无权访问所请求的资源或操作，或者请求来自该密钥 IP 列表之外的地址 |
| 带有 `"code": "application_deleted"` 的 **403** | 该密钥属于已被删除的应用。删除后的几分钟内，API 会返回此响应，随后会像对待任何无效密钥一样拒绝该密钥。请勿重试：该应用及其密钥已不复存在。 |
| **404** | 对于会话路由：该会话超出了该密钥允许的工作流或状态范围 |[API 错误](https://docs.didit.me/zh/integration/api-errors.md)页面列出了所有的状态、响应体和代码。***## 限定范围的 API 密钥为每个服务或合作伙伴分配其专属密钥，而不是共享主要密钥。
每个密钥都有其独立的访问权限：对每类资源（会话、决策、媒体、个人、企业、交易、工作流、Webhook、应用设置、分析）设置为无、只读或读写，还可选择将密钥限制为仅适用于某些工作流或已通过的会话、仅允许来自特定 IP 地址列表的请求，并设置到期日期。
您可以在 24 小时重叠期内轮换密钥，也可以立即将其撤销。在限定范围访问功能推出之前创建的密钥将保留完整访问权限。请参阅 [API 密钥](https://docs.didit.me/zh/console/api-keys.md)，了解预设、各项预设涵盖的资源，以及 API 如何响应限定范围的密钥。> [!TIP]
>
> 如果您收到 `401` 错误，请仔细核对您是否针对正确的应用使用了正确的 API 密钥，并确认该密钥未被重新生成。


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