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

概述

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，以下 endpoint 均已据此核对。

基础 URL

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

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

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

快速开始

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

步骤 1 注册

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）：

{
  "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 验证验证码并获取凭据

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）：

{
  "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 请求头发送。

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

步骤 3 使用 API

curl https://verification.didit.me/v3/sessions/ \
  -H "x-api-key: sk_live_example_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

后续登录

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

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。

在控制台中创建的邮箱/密码账户，在邮箱验证完成后同样可以使用 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 响应体如下所示：

{ "detail": "Too many login attempts from this IP address. Please wait before trying again." }

验证 API 的速率限制（例如每分钟 600 个会话）相互独立，记录在速率限制中。

管理应用

通过身份验证后，您可以在所属组织内查询、创建或更新应用。这非常适合希望为每位客户分配一个应用的经销商。每个应用都有各自的 client_id、api_key、元数据和设置。当您的组织拥有需要分开管理的不同产品、品牌、地区、环境或用例时，这种方式同样有用。

# 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 参考。

MCP 服务器集成

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

{
  "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 概览和各客户端安装指南。

错误响应结构参考

所有 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，参见速率限制。

指南

身份认证

模型上下文协议（MCP）

Web SDK

原生 SDK

服务端 SDK

集成

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

概述

基础 URL

快速开始

步骤 1 注册

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

步骤 3 使用 API

后续登录

登录时需要额外验证

密码要求

速率限制与账户锁定

管理应用

注册后智能体可以做什么

MCP 服务器集成

错误响应结构参考

​概述

​基础 URL

​快速开始

​步骤 1 注册

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

​步骤 3 使用 API

​后续登录

​登录时需要额外验证

​密码要求

​速率限制与账户锁定

​管理应用

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

​MCP 服务器集成

​错误响应结构参考

概述

基础 URL

快速开始

步骤 1 注册

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

步骤 3 使用 API

后续登录

登录时需要额外验证

密码要求

速率限制与账户锁定

管理应用

注册后智能体可以做什么

MCP 服务器集成

错误响应结构参考