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

# APIでDidit認証を設定する

> オーナーが承認した権限付与、または認証スコープのAPIキーを使い、サインイン方法・設定・ブランディング・保護をDidit認証のコードから有効化できます。

Didit Authenticationを使うと、サインイン方法を有効にしたり、アプリケーションの設定をAPIで読み取ったりできます。オーナーが承認したグラント、または `authentication`スコープを持つ名前付きのAPIキーを使用してください。

> [!WARNING]
>
> Authenticationは新機能です。まずサンドボックスアプリケーションで方法を設定し、その後に本番環境のアプリケーションで設定してください。

以下のすべての呼び出しは、アプリケーションのAuthentication管理APIに送信されます。`MANAGEMENT_BASE`は次のとおりです：

```text theme={null}
https://apx.didit.me/auth/v2/organizations/{org_id}/applications/{application_id}/authentication/
```

同じルートは`openapi-authentication.json`の`Setup`タグに記載されています。サーバーSDKはこのファイルから再生成されます。

## どの認証情報を使うか

次の3種類の認証情報のいずれも使用できます。それぞれ、所有者が承認した範囲に限られます。

| 認証情報 | 送信方法 | できること |
| - | - | - |
| `authentication` スコープを持つ名前付きAPIキー | `x-api-key: <key>` | 自身のアプリケーションを設定し、その内容を読み取ります。`read` を持つキーはセットアップの読み取りのみ可能です。`write` を持つキーは読み取りと変更の両方が可能です。 |
| 所有者が承認した `didit:management` 権限付与 | `Authorization: Bearer <access_token>` | 同意時に承認された組織のアプリケーションを、本人の役割の範囲内で設定します。 |
| コンソールセッション | `Authorization: Bearer <console session token>` | 本人の組織への所属と役割に応じて、設定の読み取りまたは変更を行います。エンドユーザー向けの表示には、コンソールセッションと適切な権限も必要です。 |

次の認証情報は、リクエストの内容にかかわらず、すべてのセットアップ用ルートで `403` により拒否されます：

* アプリケーションの**プライマリシークレット**。
* `POST /programmatic/login` から発行されたトークン。これはコンソールではなく、アプリケーション向けに発行されます。
* `authentication` スコープを**持たない**キー。すべてのリソースを最上位レベルに設定して作成したキーも含まれます。これらは「フルアクセス」と表示され、`scopes` は空のままで、これらのルートでは受け付けられません。
* 別のアプリケーションのキー、`didit:verification` のみに限定された付与、または別の組織向けに承認された付与。

認証情報が一切ない場合、リクエストは `401` を返します。付与やキーには、それ自体の制限がさらに適用されます。付与の場合はスコープ、組織、本人の役割が、キーの場合はスコープ、IP許可リスト、有効期限が適用されます。

## アクセスの承認

### 名前付きAPIキーを使う

[Business Console](https://business.didit.me)で **Developers -> API keys** を開き、設定するアプリケーション用のキーを作成します。`authentication` リソースには **読み取り** または **書き込み** を付与してください。読み取りは設定を読み取るすべての呼び出し（`GET`）に使えます。書き込みは設定を変更するすべての呼び出し（`POST`、`PUT`、`PATCH`、`DELETE`）に使え、設定の読み取りにも使えます。有効期限、IP許可リスト、ローテーションについては[APIキー](https://docs.didit.me/ja/console/api-keys.md)を参照してください。キーは1つのアプリケーションに属し、そのアプリケーションに対してのみ機能します。

### MCP接続経由

Didit MCPサーバーに接続したエージェントは、所有者が同意画面で承認したグラントを使い、`didit:management` でアクセスします。詳しくは[MCP認証](https://docs.didit.me/ja/integration/mcp/authentication.md#didit-でログイン)を参照してください。

### パスワードを持たない所有者向け

デバイスコードグラント（[RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)）を使うと、Google、パスキー、またはメールで届くコードでサインインする所有者は、パスワードを入力せずに、どのブラウザからでも同じアクセスを承認できます。詳しくは[ブラウザを使わないサインイン](https://docs.didit.me/ja/integration/mcp/authentication.md#デバイスコードでのサインイン（ブラウザーなし）)を参照してください。

## メールコードを有効にする

`PUT methods/{name}/` では、認証情報を必要としないメソッドの場合に限り `enabled` のみを指定します。

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/code/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'
```

レスポンスには、現在の状態のメソッドが返されます:

```json theme={null}
{"name": "code", "enabled": true}
```

設定を読み取ると、メールコードのエントリには `credential_source: null` が含まれます。常に有効なメソッドは無効にできません。そのリクエストへのレスポンスは `{"enabled": "always_on"}` です。

## Google を有効にする

ソーシャル認証方式では、ご自身の OAuth アプリの認証情報を使用します。サンドボックスアプリケーションの場合は、Didit のテストアプリの認証情報も使用できます。

### 独自のGoogleアプリを使う

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/google/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "credentials": {"client_id": "1234.apps.googleusercontent.com", "client_secret": "GOCSPX-..."}}'
```

レスポンスが返す `callback_uri` を、プロバイダーに登録してください。シークレットは書き込み専用で、どのレスポンスにも返されません。読み取れるのは `client_id` のみです。以前に認証情報が保存されていない状態で、認証情報なしに方式を有効にすると、`{"credentials": "required"}` が返されます。

### Didit のテストアプリ(`didit_test`)を使う

サンドボックスアプリケーションでは、ご自身のソーシャルアプリの代わりに Didit 独自のソーシャルアプリを使用できます。セットアップを完了して動作を確認するには、これで十分です。

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/google/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "credential_source": "didit_test"}'
```

`didit_test` は、サンドボックスアプリケーションに限り **Google、Microsoft、Apple、GitHub** に対応しています。

| 応答 | 条件 |
| - | - |
| `{"credential_source": "sandbox_only"}` | アプリケーションが本番環境にあります。テストアプリが本番のサインインに使われることはありません。 |
| `{"credential_source": "unavailable"}` | デプロイ環境に、そのプロバイダー用のテストアプリがありません。この方式は無効のままです。 |
| `configured: true` を含む `200` | テストアプリがこの方式に対応しており、ホスト型サインインでこの方式が提供されます。 |

設定に対する `GET` は、このアプリケーションでテストアプリが提供できるプロバイダーを `didit_test_credentials` に示します。本番環境のアプリケーションでは、4つのプロバイダーすべてで `false` になります。

## 設定を読み取る

`GET` を `MANAGEMENT_BASE` に対して呼び出すと、設定を読み取れます。各方式の `enabled` と `credential_source`、コールバックURL、セッションのルール、サインアップポリシーが返されます。

```bash theme={null}
curl --fail-with-body "$MANAGEMENT_BASE" -H "x-api-key: $DIDIT_API_KEY"
```

```json theme={null}
{
  "enabled": true,
  "methods": [
    {"name": "code", "enabled": true, "credential_source": null},
    {"name": "google", "enabled": true, "credential_source": "didit_test", "configured": true, "client_id": "didit-test-google"},
    {"name": "password", "enabled": false, "credential_source": null}
  ],
  "didit_test_credentials": {"google": true, "microsoft": true, "apple": true, "github": true},
  "redirect_uris": ["https://app.example.com/auth/callback"]
}
```

無効な方式も一覧に含まれるため、1回の `GET` で有効な方式と無効な方式の両方を確認できます。認証がアプリケーションで無効になっている場合、先頭の `enabled` は `false` になります。その場合、管理用の権限または名前付きのAPIキーを使ったどの設定変更も `{"detail": "product_disabled"}` を伴う `409` を返し、何も書き込まれません。設定のAPI呼び出しだけで認証が有効になることはありません。認証を有効にするのは担当者がコンソールでアプリケーションに対して行い、それ以降はAPI呼び出しが機能します。

## 残りのセットアップ

| `MANAGEMENT_BASE` 配下のルート | メソッド | 内容 |
| - | - | - |
| `settings/` | `GET`, `PATCH` | エージェントアクセス、組織、MFAポリシー、デフォルトのメンバーロール、無効化されたWebhookイベント |
| `onboarding/` | `GET`, `PATCH` | 完了済みのセットアップステップと、サインインをホスト型ページで行うか、独自の画面で行うか |
| `branding/` | `GET`, `PATCH` | ホスト型ページのテキストと法的リンク(ロゴと色はカスタマイズから設定されます) |
| `protection/` | `GET`, `PATCH` | ボット対策ポリシー([ボット保護](https://docs.didit.me/ja/authentication/bot-protection.md)) |
| `verified/` | `GET`, `PATCH` | サインアップ時の認証レベル、ステップアップルール、トークンクレーム |
| `emails/`, `emails/{key}/` | `GET` | このアプリケーションが送信するサインインメールと、レンダリング済みのプレビュー |
| `domain/` | `GET`, `PUT`, `DELETE` | ホスト型のオリジンとカスタムのサインインドメイン |
| `domain/verify/`, `domain/activate/` | `POST` | ドメインのDNSと証明書を確認し、正規のオリジンとして有効化する |
| `native-apps/` | `GET`, `PUT` | アプリケーションのパスキーを共有するiOSアプリとAndroidアプリ |

グラントまたはキーでは、セットアップとそのカウンターは扱えますが、エンドユーザーのデータは扱えません。`users/`、`sessions/`、`sign-ins/`、`overview/`、顧客組織、ロール、インポート、エージェントセッション、テストメールには、引き続きコンソールセッションが必要です。

`agent_humans_only` 設定は、アプリケーション全体に適用されます。変更できるのは組織のオーナーまたは管理者のみです。名前付きキーで変更しようとすると `403 owner_or_admin_required` が返されます。この設定を有効にするには、登録済みのパスキーも必要です(`passkey_required`)。

## エラー

| レスポンス | 意味 |
| - | - |
| `401` | 認証情報がありません。 |
| `403` | このアプリケーションを設定できない認証情報、または認証情報自体の制限に該当する場合です: `ip_not_allowed`、期限切れのキー、書き込み系エンドポイントに対する読み取り専用のキー。 |
| `409 {"detail": "product_disabled"}` | このアプリケーションでは認証が無効になっているため、付与されたアクセス権またはAPIキーによる設定変更は拒否されます。有効にするには、コンソールで担当者が操作する必要があります。 |
| `400 {"<field>": "<code>"}` | `sandbox_only`、`unavailable`、`not_supported`、`required`、`always_on`、`method_unavailable`、`unknown_field`。 |
| `404` | リクエストされたリソースが見つかりません。 |


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