> ## 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.

# 程序化注册：面向 AI 智能体的 KYC API

> 无需浏览器，仅需 2 次 API 调用即可注册 Didit 并获取 API 凭证。Didit 是专为 Cursor、Claude、Devin 等 AI 智能体打造的原生身份验证平台。

## 概述

Didit 是**对智能体最友好的身份验证平台**。AI 编程智能体（Cursor、Claude Code、GitHub Copilot、Devin、OpenHands、Codex）无需打开浏览器，即可通过编程方式完成注册、配置工作流并开始身份验证。

**智能体为何青睐 Didit：**

* **从零到获取凭据仅需 2 次 API 调用**（register + verify-email）。
* **无需浏览器**，完全无界面运行，非常适合 CI/CD 和智能体工作流。
* **新 API 账户无需第二因素**：完成邮箱验证后即刻返回 token。
* **自动配置**组织和应用，验证响应中包含 `api_key`。
* **完整的管理 API**，可通过 API 配置工作流、问卷、名单、计费等所有内容。
* **提供 MCP 服务器**，智能体可原生发现并使用 Didit 工具。

完整协议已发布为 [openapi-auth.json](https://docs.didit.me/openapi-auth.json)，以下 endpoint 均已据此核对。

## 基础 URL

本指南中的所有 endpoint 都位于**认证主机**上：

```
https://apx.didit.me/auth/v2
```

这与身份验证 API（`https://verification.didit.me/v3`）是不同的主机。认证主机签发 JWT 访问 token 并管理应用。验证主机负责会话、AML、工作流等功能，使用您通过本流程获得的长期有效 `api_key` 进行身份验证。

## 快速开始

> [!WARNING]
>
> **请使用真实且能够收到邮件的邮箱地址。** 该 endpoint 会同步发送验证码，因此邮件投递系统会拒绝这些保留的测试域名（`@example.com`、`@example.org`、`@*.test`、`@*.example`、`@*.invalid`），接口将返回 `500`。请将下方示例中的占位符 `you@yourdomain.com` 替换为您可以查收邮件的邮箱地址。

### 步骤 1 注册

```bash theme={null}
curl -X POST https://apx.didit.me/auth/v2/programmatic/register/ \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourdomain.com", "password": "MyStr0ng!Pass"}'
```

**响应**（`201 Created`）：

```json theme={null}
{
  "message": "Registration successful. Check your email for the verification code.",
  "email": "you@yourdomain.com"
}
```

一个由 6 位字母和数字组成的验证码（例如 `A3K9F2`）会发送到该邮箱。**验证码在发送后 10 分钟过期**。如果已过期，请使用相同的邮箱和密码再次调用此 endpoint：对于尚未验证的账户，它会返回 `200` 以及 `"A new verification code has been sent to your email."`，并附带新的验证码。另有专用的 `POST /programmatic/resend-otp/` endpoint（请求体：`{"email", "password"}`）也可以重新发送验证码，两次发送之间有 60 秒冷却时间；两个路径都共享下方的注册速率限制。

### 步骤 2 验证验证码并获取凭据

```bash theme={null}
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 OK`）：

```json theme={null}
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 86400,
  "organization": {
    "uuid": "a1b2c3d4-5678-90ab-cdef-111111111111",
    "name": "developer"
  },
  "application": {
    "uuid": "b2c3d4e5-6789-01bc-defg-222222222222",
    "name": "developer",
    "client_id": "S9LIYGSoWNuGMLHsvEt9dQ",
    "api_key": "sk_live_example_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}
```

至此您已具备所需的全部内容。请妥善保存 `application.api_key`，并在每次调用验证 API 时将其作为 `x-api-key` 请求头发送。

> [!NOTE]
>
> token 为 **RS256 签名的 JWT**。`expires_in` 默认为 **86400 秒（24 小时）**。访问 token 仅用于 `apx.didit.me/auth/v2` 上的管理 endpoint；`verification.didit.me/v3` 上的验证 API 流量使用的是长期有效的 `api_key` 进行身份验证，而不是 JWT。

### 步骤 3 使用 API

```bash theme={null}
curl https://verification.didit.me/v3/sessions/ \
  -H "x-api-key: sk_live_example_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

## 后续登录

在任何后续设备上，您都可以用邮箱和密码换取新的 JWT：

```bash theme={null}
curl -X POST https://apx.didit.me/auth/v2/programmatic/login/ \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourdomain.com", "password": "MyStr0ng!Pass"}'
```

该请求直接返回 `access_token` 和 `refresh_token`，无需浏览器。之后，调用 `GET /organizations/me/` 获取您的 `org_id`（即组织的 `uuid`），再调用 `GET /organizations/me/{org_id}/applications/` 列出组织的应用（每个条目的 `uuid` 即 `app_id`），最后调用 `GET /organizations/me/{org_id}/applications/{app_id}/` 取回 `api_key`。

> [!NOTE]
>
> 在控制台中创建的邮箱/密码账户，在邮箱验证完成后同样可以使用 `POST /programmatic/login/`。仅通过 OAuth 创建的控制台账户，需要先设置密码，才能使用这一无界面登录 endpoint。

### 登录时需要额外验证

`POST /programmatic/login/` 仅在账户没有第二因素时返回 token。
另外还有三种可能的响应，编写登录脚本的智能体需要做好处理：

| 账户情况 | 响应 |
| - | - |
| 已设置身份验证器应用或通行密钥 | 返回 `200`，内容为 `{"2fa_required": true, "temp_token": "...", "has_passkeys": true, "has_authenticator": false}`，且不包含任何 token |
| 所属组织强制启用 SSO | 返回 `403`，内容为 `{"error": "sso_required", "message": "...", "organization_name": "...", "organization_slug": "...", "sso_url": "/sso/<slug>"}` |
| 已恢复但尚未设置任何登录方式 | 返回 `403`，并包含 `"code": "recovery_setup_required"`；用于设置登录方式的链接会发送至该账户的邮箱 |

API 密钥无需登录，因此所有自动化任务都应使用 API 密钥。启用了第二因素的账户无法通过此 endpoint 完成登录。

## 密码要求

密码由服务器端强制校验，**每次只检查一条规则**。首个失败项会立即中断校验，并返回纯数组形式的错误，例如 `["Password must contain at least one uppercase letter."]`。（该 endpoint 的其他验证错误使用以字段为键的 `{"password": [...]}` 结构。密码强度规则返回纯数组格式是服务器端已知的不一致问题；在客户端代码中，请将其视为 `{"password": [...]}` 处理。）

| 规则 | 详情 |
| - | - |
| 最小长度 | 8 个字符 |
| 大写字母 | 至少包含一个 `A–Z` |
| 小写字母 | 至少包含一个 `a–z` |
| 数字 | 至少包含一个 `0–9` |
| 特殊字符 | 至少包含以下字符之一：`!@#$%^&*()_+-=[]{}\|;:,.<>?` |

## 速率限制与账户锁定

这三项相互独立的控制措施用于保护认证主机。任何一项都可能触发 `429` 响应；`Retry-After` 响应头会告诉您需要等待多久再重试。

| 范围 | 限制 |
| - | - |
| 注册 | 每个 **IP** 每小时 **5** 次尝试（与 `POST /programmatic/resend-otp/` 共享）。 |
| 邮箱验证 | 每个**邮箱**每小时 **10** 次验证码尝试，每个来源 **IP** 每小时 **50** 次，并且两次尝试之间采用指数退避（30 秒起，每次失败后翻倍，最长 1 小时）。 |
| 登录（IP） | 每个 **IP** 每分钟 **20** 次尝试，以及每个 **IP** 每小时 **100** 次尝试。 |
| 登录（邮箱） | 针对账户的渐进式锁定：连续 **5** 次失败 → 锁定 15 分钟；**10** 次 → 1 小时；**20** 次 → 24 小时。 |

`429` 响应体如下所示：

```json theme={null}
{ "detail": "Too many login attempts from this IP address. Please wait before trying again." }
```

验证 API 的速率限制（例如每分钟 600 个会话）相互独立，记录在[速率限制](https://docs.didit.me/zh/integration/rate-limiting.md)中。

## 管理应用

通过身份验证后，您可以在所属组织内查询、创建或更新应用。

这非常适合希望为每位客户分配一个应用的**经销商**。每个应用都有各自的 `client_id`、`api_key`、元数据和设置。当您的组织拥有需要分开管理的不同产品、品牌、地区、环境或用例时，这种方式同样有用。

```bash theme={null}
# 1. Discover your org_id
curl https://apx.didit.me/auth/v2/organizations/me/ \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 2. List the organization's applications (each entry's uuid is an app_id)
curl "https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 3. Create an application for a customer, product, or environment
curl -X POST "https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Customer App",
    "website_url": "https://acme.example",
    "redirect_uris": ["https://acme.example/callback"],
    "terms_url": "https://acme.example/terms",
    "privacy_url": "https://acme.example/privacy"
  }'

# 4. Recover credentials (client_id + api_key) for an existing application
curl "https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/$APP_ID/" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 5. Update application metadata (PATCH — uuid, client_id, api_key never change)
curl -X PATCH "https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/$APP_ID/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Production App",
    "website_url": "https://app.acme.example"
  }'
```

列出、创建或更新应用要求用户是目标组织的**所有者**或**管理员**，否则响应为 `403`。

## 注册后智能体可以做什么

使用 `api_key` 时，智能体可以完全访问验证 API。`https://verification.didit.me/v3` 上已审计的路径如下：

| API | 功能 |
| - | - |
| `POST /v3/session/` | 创建验证会话。 |
| `GET /v3/sessions/` | 列出会话。 |
| `GET /v3/session/{id}/decision/` | 获取 V3 决策（复数数组，参见数据模型）。 |
| `GET /v3/workflows/` | 列出验证工作流。 |
| `GET /v3/questionnaires/` | 列出自定义问卷。 |
| `GET /v3/users/` | 列出终端用户（按 `vendor_data` 索引）。 |
| `GET /v3/billing/balance/` | 查询额度余额。 |
| `POST /v3/billing/top-up/` | 为额度充值。 |
| `GET /v3/webhook/destinations/` | 管理 Webhook 目标（列出 / 创建 / 更新 / 删除）。 |

完整的接口范围请参阅[管理 API 参考](https://docs.didit.me/zh/sessions-api/management-api.md)。

## MCP 服务器集成

为获得最佳的智能体体验，请使用托管的 Didit MCP 服务器，地址为 `https://mcp.didit.me/mcp`。它无需 API 密钥：首次连接时，客户端会打开浏览器，您点击 **使用 Didit 登录**（OAuth 2.1 配合 PKCE），服务器将以您的身份执行操作，并遵循您在控制台中的角色权限。原生支持远程 MCP 的客户端（Cursor、VS Code）直接使用此配置；Claude 网页版和桌面版则将其添加为自定义连接器：

```json theme={null}
{
  "mcpServers": {
    "didit": {
      "url": "https://mcp.didit.me/mcp"
    }
  }
}
```

Claude Code：`claude mcp add --transport http didit https://mcp.didit.me/mcp`。仅支持 stdio 的客户端（Windsurf、Zed）通过 `mcp-remote` 桥接工具连接，该工具会为您执行 OAuth 流程。

您在上述注册流程中获得的 API 密钥用于从您自己的后端调用 REST API；MCP 永远不会使用该密钥。详情请参阅 [MCP 概览](https://docs.didit.me/zh/integration/mcp/overview.md)和[各客户端安装指南](https://docs.didit.me/zh/integration/mcp/installation.md)。

## 错误响应结构参考

所有 `apx.didit.me/auth/v2` endpoint 都使用相同的三种响应结构（参见 `openapi-auth.json`）：

* **字段级校验**：`{"field": ["message", ...]}`，HTTP `400`。
* **表单级校验**（尤其是密码强度和验证码错误）：纯数组 `["Invalid or expired verification code."]`，HTTP `400`。
* **身份验证与业务规则**：`{"detail": "..."}`，状态码为 `400`、`401`、`403`、`404` 或 `429`。`429` 响应包含 `Retry-After` 响应头，告诉您需要等待多久再重试（响应体仅包含 `detail`）。

验证主机以 `{"detail": "..."}` 的形式返回错误，429 响应包含 `X-RateLimit-*` 和 `Retry-After`，参见[速率限制](https://docs.didit.me/zh/integration/rate-limiting.md)。


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