プログラムによる登録：AIエージェント向けKYC API

概要

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として公開されており、以下のエンドポイントはこの仕様と照合して検証されています。

ベースURL

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

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

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

クイックスタート

実在する、配信可能なメールアドレスを使用してください。 このエンドポイントは認証コードを同期的に送信するため、予約済みのテスト用ドメイン（@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分後に失効します。失効した場合は、同じメールアドレスとパスワードでこのエンドポイントを再度呼び出してください。まだ認証されていないアカウントであれば、200と"A new verification code has been sent to your email."が返され、新しいコードが送信されます。専用のPOST /programmatic/resend-otp/エンドポイント（ボディ: {"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ヘッダーとして送信してください。

トークンはRS256で署名されたJWTです。expires_inのデフォルトは86400秒（24時間）です。アクセストークンが必要なのはapx.didit.me/auth/v2上の管理エンドポイントだけです。verification.didit.me/v3への検証APIのトラフィックは、JWTではなく長期有効なapi_keyで認証されます。

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

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

2回目以降のログイン

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

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

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のボディは次のようになります。

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

Verification APIのレート制限(例: 1分あたり600セッション)はこれとは独立しており、レート制限に記載されています。

アプリケーションの管理

認証後は、組織内のアプリケーションを取得、作成、更新できます。これは、顧客ごとに1つのアプリケーションを用意したいリセラーに最適です。各アプリケーションには固有の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"
  }'

アプリケーションの一覧取得、作成、更新を行うには、ユーザーが対象組織の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リファレンスを参照してください。

MCPサーバー連携

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

{
  "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のすべてのエンドポイントは、同じ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が含まれます。レート制限を参照してください。

ガイド

認証

Model Context Protocol (MCP)

Web SDK

ネイティブSDK

サーバーSDK

連携

プログラムによる登録：AIエージェント向けKYC API

概要

ベースURL

クイックスタート

ステップ1: 登録

ステップ2: コードを検証して認証情報を取得する

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

2回目以降のログイン

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

パスワード要件

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

アプリケーションの管理

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

MCPサーバー連携

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

​概要

​ベースURL

​クイックスタート

​ステップ1: 登録

​ステップ2: コードを検証して認証情報を取得する

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

​2回目以降のログイン

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

​パスワード要件

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

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

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

​MCPサーバー連携

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

概要

ベースURL

クイックスタート

ステップ1: 登録

ステップ2: コードを検証して認証情報を取得する

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

2回目以降のログイン

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

パスワード要件

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

アプリケーションの管理

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

MCPサーバー連携

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