> ## 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認証情報を取得できます。Cursor、Claude、Devinに対応した、最もエージェントネイティブな本人確認プラットフォームです。

## 概要

Didit は**最もエージェントフレンドリーな本人確認プラットフォーム**です。AIコーディングエージェント（Cursor、Claude Code、GitHub Copilot、Devin、OpenHands、Codex）は、ブラウザを一度も開かずに、登録、ワークフローの設定、本人確認の開始までをすべてプログラムから実行できます。

**エージェントにDiditが選ばれる理由:**

* **2回のAPI呼び出し**で、ゼロから認証情報の取得まで完了します（register + verify-email）。
* **ブラウザ不要**：完全にヘッドレスで、CI/CDやエージェントのワークフローに最適です。
* **新規APIアカウントでは第2要素認証は不要です**：メール認証の直後にトークンが返されます。
* **自動プロビジョニング**：組織とアプリケーションが自動で作成され、verifyのレスポンスに`api_key`が含まれます。
* **フル機能の管理API**：ワークフロー、アンケート、リスト、請求をすべてAPIで設定できます。
* **MCP サーバー**を提供：エージェントがDiditのツールをネイティブに検出して利用できます。

完全な仕様は[openapi-auth.json](https://docs.didit.me/openapi-auth.json)として公開されており、以下のエンドポイントはこの仕様と照合して検証されています。

## ベースURL

このガイドのエンドポイントはすべて**認証ホスト**上にあります:

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

これは検証API（`https://verification.didit.me/v3`）とは別のホストです。認証ホストはJWTアクセストークンを発行し、アプリケーションを管理します。検証ホストは、このフローで取得する長期間有効な`api_key`で認証され、セッション、AML、ワークフローなどを実行します。

## クイックスタート

> [!WARNING]
>
> **実在する、配信可能なメールアドレスを使用してください。** このエンドポイントは認証コードを同期的に送信するため、予約済みのテスト用ドメイン（`@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分後に失効します**。失効した場合は、同じメールアドレスとパスワードでこのエンドポイントを再度呼び出してください。まだ認証されていないアカウントであれば、`200`と`"A new verification code has been sent to your email."`が返され、新しいコードが送信されます。専用の`POST /programmatic/resend-otp/`エンドポイント（ボディ: `{"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]
>
> トークンは**RS256で署名されたJWT**です。`expires_in`のデフォルトは\*\*86400秒（24時間）\*\*です。アクセストークンが必要なのは`apx.didit.me/auth/v2`上の管理エンドポイントだけです。`verification.didit.me/v3`への検証APIのトラフィックは、JWTではなく長期有効な`api_key`で認証されます。

### ステップ3: APIを使用する

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

## 2回目以降のログイン

今後はどのマシンからでも、メールアドレスとパスワードを使用して新しい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のみのコンソールアカウントは、このヘッドレスログインエンドポイントを使用する前にパスワードを設定する必要があります。

### ログインで追加の対応が求められる場合

`POST /programmatic/login/`がトークンを返すのは、アカウントに第二要素がない場合のみです。
それ以外に3種類の応答があり得るため、ログインをスクリプト化するエージェントはこれらに対応する必要があります:

| アカウント | レスポンス |
| - | - |
| 認証アプリまたはパスキーを設定している | `200`と`{"2fa_required": true, "temp_token": "...", "has_passkeys": true, "has_authenticator": false}`が返され、トークンは含まれない |
| 組織がSSOを必須にしている | `403`と`{"error": "sso_required", "message": "...", "organization_name": "...", "organization_slug": "...", "sso_url": "/sso/<slug>"}`が返される |
| 復旧済みで、まだサインイン方法がない | `403`と`"code": "recovery_setup_required"`が返され、サインイン方法を設定するためのリンクがアカウントのアドレスに送信される |

APIキーはログインが不要なため、自動化する処理にはAPIキーを使用してください。第二要素を持つアカウントは、このエンドポイントからサインインを完了できません。

## パスワード要件

サーバー側で**1つずつ順番に**適用されます。最初に違反したルールで処理が打ち切られ、`["Password must contain at least one uppercase letter."]`のような配列だけのエラーが返されます。（このエンドポイントのその他のバリデーションエラーは、フィールドをキーとする`{"password": [...]}`形式のエンベロープを使用します。パスワード強度ルールでの配列だけの形式はサーバー側の既知の不整合です。クライアントコードでは`{"password": [...]}`として扱ってください。）

| ルール | 詳細 |
| - | - |
| 最小文字数 | 8文字 |
| 大文字 | `A–Z`を1文字以上 |
| 小文字 | `a–z`を1文字以上 |
| 数字 | `0–9`を1文字以上 |
| 特殊文字 | `!@#$%^&*()_+-=[]{}\|;:,.<>?`のうち1文字以上 |

## レート制限とロックアウト

認証ホストは3つの独立した制御で保護されています。いずれの制御でも`429`レスポンスが返されることがあり、`Retry-After`レスポンスヘッダーで待機すべき時間がわかります。

| 対象 | 制限 |
| - | - |
| 登録 | **IP**ごとに**1時間**あたり**5**回の試行(`POST /programmatic/resend-otp/`と共有)。 |
| メール認証 | **メール**ごとに**1時間**あたり**10**回のコード試行、送信元**IP**ごとに**1時間**あたり**50**回。さらに試行間に指数バックオフ(30秒から失敗ごとに倍増、上限は1時間)が適用されます。 |
| ログイン(IP) | **IP**ごとに**1分**あたり**20**回、および**IP**ごとに**1時間**あたり**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." }
```

Verification APIのレート制限(例: 1分あたり600セッション)はこれとは独立しており、[レート制限](https://docs.didit.me/ja/integration/rate-limiting.md)に記載されています。

## アプリケーションの管理

認証後は、組織内のアプリケーションを取得、作成、更新できます。

これは、顧客ごとに1つのアプリケーションを用意したい**リセラー**に最適です。各アプリケーションには固有の`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"
  }'
```

アプリケーションの一覧取得、作成、更新を行うには、ユーザーが対象組織の**owner**または**admin**である必要があります。そうでない場合、レスポンスは`403`になります。

## 登録後にエージェントができること

`api_key`があれば、エージェントはVerification 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の送信先を管理します(一覧 / 作成 / 更新 / 削除)。 |

全体については[Management APIリファレンス](https://docs.didit.me/ja/sessions-api/management-api.md)を参照してください。

## MCPサーバー連携

最適なエージェント体験のために、`https://mcp.didit.me/mcp`のホスト型Didit MCPサーバーを使用してください。APIキーは不要です。初回接続時にクライアントがブラウザを開き、**Log in with Didit**(PKCE付きOAuth 2.1)すると、サーバーは、コンソール上のあなたの役割に付与された権限で、あなたとして動作します。リモートMCPをネイティブにサポートするクライアント(Cursor、VS Code)はこのエントリーを使用し、Claude WebとDesktopではカスタムコネクターとして追加します。

```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/ja/integration/mcp/overview.md)と[クライアント別のインストール](https://docs.didit.me/ja/integration/mcp/installation.md)を参照してください。

## エラーエンベロープリファレンス

`apx.didit.me/auth/v2`のすべてのエンドポイントは、同じ3種類のレスポンス形式を共有しています(`openapi-auth.json`を参照)。

* **フィールドレベルのバリデーション**: HTTP `400`で`{"field": ["message", ...]}`を返します。
* **フォームレベルのバリデーション**(特にパスワード強度と認証コードのエラー): HTTP `400`でそのままの`["Invalid or expired verification code."]`を返します。
* **認証 / ビジネスルール**: `400`、`401`、`403`、`404`、または`429`で`{"detail": "..."}`を返します。`429`レスポンスには、待機すべき時間を示す`Retry-After`レスポンスヘッダーが含まれます(ボディには`detail`のみが含まれます)。

検証ホストはエラーを`{"detail": "..."}`として返し、429には`X-RateLimit-*`と`Retry-After`が含まれます。[レート制限](https://docs.didit.me/ja/integration/rate-limiting.md)を参照してください。


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