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

# Auth API 程序化注册：通过 API 创建 Didit 组织

> 通过 Auth API 以程序方式创建 Didit 组织，无需浏览器，由智能体原生调用。可构建子账户 KYC 基础设施，按次付费，无需签订合同。



Programmatic Register Prompt
        将提示词复制到剪贴板



      
      

\<pre>

\``Programmatically create a pending Didit account — step 1 of the two-step onboarding (no browser, no console).

Endpoint:
POST https://apx.didit.me/auth/v2/programmatic/register/

Authentication:
None. This is a public endpoint. (Don't confuse the Auth API host `apx.didit.me/auth/v2` with the verification host `verification.didit.me/v3`.)

Request body:
\- email (string, required) — Any real, deliverable email (personal, work, alias). The verification code is mailed synchronously, so reserved test domains (`@example.com`, `@example.org`, `@*.test`, `@*.example`, `@*.invalid`) get rejected by mail delivery and the call returns `500` — substitute the placeholder with an inbox you can read.
\- password (string, required) — Must satisfy ALL of: minimum 8 characters, ≥1 uppercase letter (A-Z), ≥1 lowercase letter (a-z), ≥1 digit (0-9), ≥1 special character from !@#$%^&*()_+-=[]{}|;:,.<>?. Rules are validated one at a time and the first failure short-circuits.

curl example (replace `you@yourdomain.com` with a real inbox):
curl -X POST https://apx.didit.me/auth/v2/programmatic/register/ \
-H "Content-Type: application/json" \
-d '{
"email": "you@yourdomain.com",
"password": "MyStr0ng!Pass"
}'

Response (201 Created):
\- message (string) — "Registration successful. Check your email for the verification code."
\- email (string) — echoed back.

What happens server-side:
\- A pending account is created (NOT usable yet).
\- A 6-character alphanumeric code (e.g. "A3K9F2") is emailed to the supplied address.
\- The code is valid for 15 minutes. After expiry the registration must be redone.

Failure modes (all 400 unless noted):
\- Field-level: { "email": ["Enter a valid email address."] } or { "password": ["Ensure this field has at least 8 characters."] }.
\- Password-strength failures CURRENTLY return as a BARE ARRAY (no field key), one rule at a time: ["Password must contain at least one uppercase letter."] / lowercase / digit / special character. Known server-side inconsistency — treat as { "password": [...] } client-side.
\- Duplicate email: { "detail": "An account with this email already exists." }
\- 429 — { "detail": "Too many registration attempts. Please try again later.", "wait": <seconds> } when more than 5 registrations from the same IP within an hour.
\- 500 — returned (with an HTML body, not JSON) when mail delivery to the supplied address fails synchronously. Most commonly triggered by reserved test domains; use a real inbox.

Rate limits:
5 registrations per IP per hour.

Next step:
After receiving the email, call POST https://apx.didit.me/auth/v2/programmatic/verify-email/ with { "email", "code" } to get your access_token and api_key — see /auth-api/verify-email.

For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.``

\</pre>



      
      

粘贴到



## OpenAPI

````yaml zh/openapi-auth.json POST /programmatic/register/
openapi: 3.0.0
info:
  version: 1.0.0
  title: Didit Auth API
  description: >-
    面向开发者和 AI 代理的程序化注册与认证 API。仅需 2 次 API 调用即可完成注册，无需浏览器。对代理最友好的身份证件验证平台。


    ## Base URL


    本规范中的所有 endpoint 均托管在 `https://apx.didit.me/auth/v2`。该主机与验证
    API（`https://verification.didit.me/v3`）不同。请务必区分它们：此认证主机负责签发您的 **JWT 访问
    token**，并允许您列出和管理您的**组织**与**应用**。验证主机则是您调用会话、工作流、AML 等服务的地方，使用此 API 返回的
    **`api_key`** 进行身份验证。


    ## 认证流程运作方式


    1. `POST /programmatic/register/`：提交邮箱 + 密码。

    2. 通过电子邮件接收 6 位字母数字验证码。

    3. `POST /programmatic/verify-email/`：提交验证码。您将获得 JWT
    `access_token`、`refresh_token`、一个组织以及带有 `client_id` + `api_key` 的默认应用。

    4. 保存 `api_key`。在对 `https://verification.didit.me/v3/...` 的每次调用中将其作为
    `x-api-key` 使用。

    5. 在将来的任何机器上，`POST /programmatic/login/` 都可以用您的邮箱 + 密码换取全新的 JWT，然后调用 `GET
    /organizations/me/` 和应用 endpoint 来恢复或轮换凭据。


    JWT 仅在用于本规范中的**账户管理** endpoint 时需要；验证 API 的流量使用的是长期有效的 `api_key`，而非 JWT。


    ## 约定


    - 所有请求体和响应体均为 JSON（`Content-Type: application/json`）。

    - **在测试 `POST /programmatic/register/` 时，请使用真实、可投递的电子邮件地址。** 该 endpoint
    会同步发送验证码，因此保留测试域名（`@example.com`、`@example.org`、`@*.test`、`@*.example`、`@*.invalid`）的地址将被邮件发送系统拒绝，且请求将返回
    `500`。请将示例中的占位符 `you@yourdomain.com` 替换为您实际可以查收的收件箱。

    - 验证错误返回 HTTP `400`，具有以下两种外层结构之一：针对字段级问题的 `{"field": ["message",
    ...]}`，或针对业务规则错误的 `{"detail":
    "message"}`。少数验证器（注册时的密码强度、验证邮箱时的验证码过期）目前会响应纯数组 `["message"]`
    而不是以字段为键的形式，这是已知的服务端不一致性，因此客户端代码应同时支持这两种结构。

    - 身份验证错误将作为 `{"detail": "..."}` 返回，状态码为 HTTP `401`（无效的 bearer token）或
    `403`（缺少 bearer token / 权限不足）。

    - 速率限制响应包含一个以秒为单位的冷却时间字段 `wait`。
servers:
  - url: https://apx.didit.me/auth/v2
    description: 生产环境认证服务器
security: []
tags:
  - name: Programmatic Auth
    description: >-
      邮箱和密码账户生命周期：注册、验证、登录。返回用于访问账户管理 endpoint 的 JWT
      `access_token`，并在验证通过时一并返回您首个应用的 `client_id` 和 `api_key`。
  - name: Account Management
    description: >-
      用于列出组织以及创建、获取或更新应用的经认证 endpoint（JWT bearer）。使用这些 endpoint 可以恢复或轮换用于验证 API
      调用身份的 `api_key`。
paths:
  /programmatic/register/:
    post:
      tags:
        - Programmatic Auth
      summary: 注册账户
      description: >-
        程序化入驻的第 1 步。创建一个待处理账户并通过电子邮件发送一个 6 位字符验证码（10 分钟
        TTL）。在创建任何账户前都会检查该地址：无法接收验证码的地址将返回 400 `email_undeliverable`。速率限制：每个 IP
        每小时 5 次，外加每个网络共享的每小时配额（IPv4 为 /24，IPv6 为 /64）。
      operationId: programmatic_register
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
            examples:
              Gmail:
                summary: 使用个人 Gmail 注册
                value:
                  email: you@yourdomain.com
                  password: MyStr0ng!Pass
              Work:
                summary: 使用工作邮箱注册
                value:
                  email: you@yourcompany.com
                  password: C0mplex#Pass1
      responses:
        '201':
          description: >-
            注册成功。一个 6 位字母数字验证码（例如 `A3K9F2`）已发送至提供的邮箱地址，有效期为 10 分钟。接下来请调用 `POST
            /programmatic/verify-email/`。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterResponse'
              examples:
                Success:
                  value:
                    message: >-
                      Registration successful. Check your email for the
                      verification code.
                    email: you@yourdomain.com
        '400':
          description: >-
            验证错误。预期外包格式为：字段级错误使用 `{"field": ["..."]}`，业务规则错误使用 `{"detail":
            "..."}`（例如邮箱重复）。密码强度规则目前会返回裸数组
            `["..."]`，一次返回一条规则，这是已知的服务端不一致性；在修复前请将其视为 `{"password": ["..."]}`
            处理。当该地址无法接收验证码时（一次性域名、保留或测试域名、无邮件服务器、疑似拼写错误或先前被退信的地址），响应体为包含 `code:
            "email_undeliverable"` 的 `EmailUndeliverableError`；不会创建或更改任何账户。
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ValidationError'
                  - $ref: '#/components/schemas/EmailUndeliverableError'
              examples:
                MissingFields:
                  summary: 空请求体
                  value:
                    email:
                      - This field is required.
                    password:
                      - This field is required.
                InvalidEmail:
                  summary: 邮箱格式错误
                  value:
                    email:
                      - Enter a valid email address.
                PasswordTooShort:
                  summary: 密码少于 8 个字符
                  value:
                    password:
                      - Ensure this field has at least 8 characters.
                PasswordMissingUppercase:
                  summary: 密码缺少大写字母
                  value:
                    - Password must contain at least one uppercase letter.
                PasswordMissingLowercase:
                  summary: 密码缺少小写字母
                  value:
                    - Password must contain at least one lowercase letter.
                PasswordMissingDigit:
                  summary: 密码缺少数字
                  value:
                    - Password must contain at least one digit.
                PasswordMissingSpecial:
                  summary: 密码缺少特殊字符
                  value:
                    - >-
                      Password must contain at least one special character
                      (!@#$%^&*()_+-=[]{}|;:,.<>?).
                Duplicate:
                  summary: 该邮箱已注册账户
                  value:
                    detail: An account with this email already exists.
                EmailUndeliverable:
                  summary: 地址无法接收电子邮件（一次性邮箱域名）
                  value:
                    detail: >-
                      This email can't receive messages. Please use a different
                      email address.
                    code: email_undeliverable
                    reason: disposable_domain
                EmailLikelyTypo:
                  summary: 域名中可能存在拼写错误
                  value:
                    detail: >-
                      This email can't receive messages. Please use a different
                      email address.
                    code: email_undeliverable
                    reason: possible_typo
                    suggestion: gmail.com
        '429':
          description: >-
            已受到速率限制。过去一小时内来自同一 IP 的注册尝试超过 5 次，或者调用方网络（IPv4 为 /24，IPv6 为
            /64，由注册和验证码重发共享）的每小时配额已用尽。两者均带有 `Retry-After:
            3600`。当服务暂时达到并发检查密码或验证码的上限时也会返回此响应，并带有 `Retry-After: 5`
            请求头；请在指定的秒数后重试。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
              examples:
                RateLimited:
                  value:
                    detail: Too many registration attempts. Please try again later.
                PasswordChecksBusy:
                  summary: 正在进行的密码检查过多
                  value:
                    detail: >-
                      Too many sign-in attempts are being processed right now.
                      Please try again in a few seconds.
      security:
        - {}
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |-
            curl -X POST https://apx.didit.me/auth/v2/programmatic/register/ \
              -H "Content-Type: application/json" \
              -d '{
                "email": "you@yourdomain.com",
                "password": "MyStr0ng!Pass"
              }'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # This call needs no API key.
            client = Didit()

            result = client.account.register(
                email="you@yourdomain.com",
                password="MyStr0ng!Pass",
            )
            print(result)
        - lang: javascript
          label: Node.js
          source: |-
            import Didit from "@didit-protocol/sdk-node";

            // This call needs no API key.
            const didit = new Didit();

            const result = await didit.account.register({
              email: "you@yourdomain.com",
              password: "MyStr0ng!Pass",
            });
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// This call needs no API key.\nclient := didit.NewClient()\n\nresult, err := client.Account.Register(ctx, didit.RegisterRequest{\n\tEmail:    \"you@yourdomain.com\",\n\tPassword: \"MyStr0ng!Pass\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: |-
            import me.didit.Didit;
            import me.didit.types.RegisterRequest;

            // This call needs no API key.
            Didit client = new Didit();

            var result = client.account().register(RegisterRequest.builder()
                    .email("you@yourdomain.com")
                    .password("MyStr0ng!Pass")
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: |-
            <?php

            require 'vendor/autoload.php';

            use Didit\DiditClient;

            // This call needs no API key.
            $didit = new DiditClient();

            $result = $didit->account->register([
                'email' => 'you@yourdomain.com',
                'password' => 'MyStr0ng!Pass',
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # This call needs no API key.
            didit = Didit::Client.new

            result = didit.account.register(
              email: "you@yourdomain.com",
              password: "MyStr0ng!Pass"
            )
            puts result.to_h
        - lang: csharp
          label: .NET
          source: |-
            using System;
            using System.Text.Json;
            using Didit;

            // This call needs no API key.
            using var client = new DiditClient();

            var result = await client.Account.RegisterAsync(new RegisterRequest
            {
                Email = "you@yourdomain.com",
                Password = "MyStr0ng!Pass",
            });
            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    RegisterRequest:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
          description: 任意有效的邮箱地址（个人、工作、别名）。用作唯一的账户标识符。
          example: you@yourdomain.com
        password:
          type: string
          minLength: 8
          description: >-
            至少 8 个字符。必须包含至少一个大写字母（`A-Z`）、一个小写字母（`a-z`）、一个数字（`0-9`）以及一个来自
            `!@#$%^&*()_+-=[]{}|;:,.<>?` 的特殊字符。验证时每次报告一条未通过的规则。
          example: MyStr0ng!Pass
    RegisterResponse:
      type: object
      properties:
        message:
          type: string
          description: 表明验证码已发送的便于人类阅读的确认信息。
          example: Registration successful. Check your email for the verification code.
        email:
          type: string
          format: email
          description: 验证码发送到的电子邮件地址。
          example: you@yourdomain.com
    ValidationError:
      description: >-
        验证错误主体。预期的包装格式为针对字段级错误的 `{field: ["message", ...]}` 映射，或针对业务规则错误的
        `{detail: "..."}` 单键包装格式。少数验证器（注册时的密码强度、邮箱验证时的验证码有效性）当前会返回单纯的数组
        `["message"]`（已知的服务端不一致情况）。以下架构保留了该单纯数组分支，以便根据本规范生成的客户端代码可以反序列化当前的响应，但新的客户端代码应将其视为以相关字段为键的形式（`{password:
        [...]}` 或 `{code: [...]}`），服务端契约也将逐步统一为该结构。
      oneOf:
        - type: object
          additionalProperties:
            type: array
            items:
              type: string
          example:
            email:
              - Enter a valid email address.
        - type: object
          properties:
            detail:
              type: string
          example:
            detail: An account with this email already exists.
        - type: array
          items:
            type: string
          example:
            - Invalid or expired verification code.
    EmailUndeliverableError:
      type: object
      description: >-
        当地址无法接收验证码时由 `POST /programmatic/register/`
        返回。该检查在创建或更改任何账户之前运行，因此不会留下任何残留数据。
      required:
        - detail
        - code
        - reason
      properties:
        detail:
          type: string
          description: 便于人类阅读的消息。
          example: >-
            This email can't receive messages. Please use a different email
            address.
        code:
          type: string
          enum:
            - email_undeliverable
          description: 始终为 `email_undeliverable`。
        reason:
          type: string
          enum:
            - invalid_address
            - reserved_domain
            - no_mail_records
            - disposable_domain
            - possible_typo
            - suppressed
          description: >-
            地址被拒绝的原因：`invalid_address`（无效地址）、`reserved_domain`（保留或测试域名，如
            `example.com`）、`no_mail_records`（该域名没有邮件服务器）、`disposable_domain`（一次性邮箱服务商）、`possible_typo`（常见服务商名称可能拼写有误；参见
            `suggestion`）、`suppressed`（该地址之前曾发生退信或投诉）。
        suggestion:
          type: string
          description: >-
            可能预期的域名，仅在域名疑似拼写错误时出现（例如用 `gmail.com` 代替 `gmial.com`）。API
            不接受确认：请使用更正后的地址重新注册。
          example: gmail.com
    RateLimitError:
      type: object
      description: 速率限制或递进式锁定响应。`wait` 为冷却时间（秒）。
      properties:
        detail:
          type: string
          example: >-
            Too many login attempts from this IP address. Please wait before
            trying again.

````

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