# 接続を作成

`POST /v1/connections` · 権限 `connections:write`

環境に新しい接続を登録します。プロトコル設定が必要な接続（`social`、`enterprise`）は `inactive` で開始されます。`:activate` を使って明示的に有効化してください。`enterprise` 接続は `active` で作成できません。新しい接続はまだサインインのテストに成功していないためです。設定にシークレットを含めることはできません。1 つの環境には最大 100 件の接続と 20 件の汎用ソーシャル（`oidc_generic`、`oauth2_generic`）接続を設定でき、1 つの組織には最大 20 件の接続を設定できます。

## リクエスト

JSON ボディ（未知のフィールドは `400 unknown_field` で拒否されます）:

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `key` | string | はい | 安定した設定キー。`^[a-z0-9_-]{1,64}$` に一致し、環境内で一意で、変更できません。 |
| `type` | string | はい | `database`、`passwordless`、`passkey`、`social`、`enterprise` のいずれか。変更できません。 |
| `strategy` | string | はい | タイプに応じた戦略（例: `password`、`email_otp`、`google`、`saml`）。変更できません。 |
| `name` | string | はい | 1〜128 文字。環境内で一意です。 |
| `display_name` | string | いいえ | サインイン画面に表示される 1〜128 文字。 |
| `status` | string | いいえ | `active` または `inactive`。`database`、`passwordless`、`passkey` の既定値は `active`、`social`、`enterprise` の既定値は `inactive` です。 |
| `org_id` | string | いいえ | 所有組織（`org_…`）。`enterprise` のみ。省略すると環境の接続になります。変更できません。 |
| `allowed_email_domains` | array of strings | いいえ | ホームレルム検出によってこの接続に振り分けられるメールドメイン。IDNA の A ラベル、小文字で指定します（例: `xn--bcher-kva.example`）。一意で、最大 100 件です。`enterprise` の場合のみ空でない値を指定できます。組織の接続では、すべてのドメインが組織の検証済みドメインである必要があり、`active` の組織接続には少なくとも 1 件が必要です。 |
| `allow_external_domains` | boolean | いいえ | 一覧にないメールドメインのユーザーもサインインできるようにします。`enterprise` のみ。既定値は `false` です。 |
| `jit_mode` | string | いいえ | ジャスト・イン・タイム・プロビジョニング。`create` は初回サインイン時にユーザーを作成し、`create_and_update` はさらに ID プロバイダーからプロフィールを更新します。`off` は既存のアカウントを必要とします。`enterprise` のみ。既定値は、環境の接続では `create_and_update`、組織の接続では `off` です。 |
| `email_trust` | boolean | いいえ | 自動アカウント連携およびジャスト・イン・タイム・プロビジョニングのために、ID プロバイダーが提示するメールアドレスを信頼します。`enterprise` のみ。既定値は `false` です。組織の接続で `true` にする場合は、空でない `allowed_email_domains` が必要で、そのすべてのドメインが組織の検証済みドメインである必要があります。 |
| `default_role_ids` | array of strings | いいえ | ジャスト・イン・タイム・サインインで作成されるメンバーシップに付与される環境のロール（`rol_…`、一意、最大 10 件）。環境の既定ロールおよび接続のグループロールマッピングに加えて付与されます。組織の `enterprise` 接続でのみ指定できます。すべてのロールは、この環境の特権を持たない環境ロールである必要があります。別の環境のロール、組織のロール、特権ロール、存在しないロールは拒否されます。後から削除されたり特権ロールに変更されたりしたロールは、サインイン時にスキップされます。 |
| `trust_idp_mfa` | boolean | いいえ | ID プロバイダーが提示する多要素認証（SAML の認証コンテキスト、OIDC の `amr`/`acr`）を、セッションの MFA の証明として受け入れます。`enterprise` のみ。既定値は `false` です。 |
| `settings` | object | いいえ | シークレットを含まない設定。最大 32 KiB です。シークレットのように見えるキーや値は拒否されます。 |
| `Idempotency-Key` | header | いいえ | 再試行されたリクエストを安全に扱うための任意のキー（16〜64 文字）。 |

## レスポンス

`201 Created` と、接続情報およびそのバージョンを保持する `ETag` ヘッダーを返します。

```json
{
  "id": "conn_0k3v8m1q2x9dz4h7s5t6w0y1ab",
  "key": "google",
  "type": "social",
  "strategy": "google",
  "name": "Google",
  "display_name": "Sign in with Google",
  "status": "inactive",
  "org_id": null,
  "allowed_email_domains": [],
  "allow_external_domains": false,
  "jit_mode": null,
  "email_trust": null,
  "default_role_ids": [],
  "trust_idp_mfa": null,
  "allow_idp_initiated": null,
  "idp_initiated_default_application_id": null,
  "idp_initiated_allowed_application_ids": [],
  "settings": {},
  "created_at": "2026-10-05T09:30:00.123456Z",
  "updated_at": "2026-10-05T09:30:00.123456Z"
}
```

## パスキーの設定

`type: "passkey"` の場合、`settings` オブジェクトには以下のキーのみ指定できます。それ以外のキー、誤った型、範囲外の値は、`422 validation_failed` と、`/settings/max_credentials_per_user` などの `errors[].pointer` を伴って拒否されます。`null` の値は既定値を意味します。形式のエラーはプランのエラーより先に報告されます。

| キー | 型 | 注記 |
|---|---|---|
| `rp_id` | string | 省略、`null`、または空の場合、各サインインホストがそれぞれ独自の rpId になります。それ以外の場合は、環境の `active` なカスタムドメインのホスト名（小文字、IDNA の A ラベル）を指定します。その他の値は `422 validation_failed`（`/settings/rp_id`）になります。環境にすでにパスキーがある場合は、[パスキーの rpId を変更](change-rp-id.md)から変更してください。 |
| `rp_name` | string | 最大 128 文字。 |
| `passkey_first_factor_enabled`、`security_key_second_factor_enabled` | boolean | 既定値は `true`。 |
| `user_verification` | string | `preferred`（既定値）または `required`。 |
| `max_credentials_per_user` | integer | 1〜20。既定値は 20。小数は拒否されます。 |
| `require_device_bound_passkeys` | boolean | プランで制限されます。`true` には Startup が必要です。 |
| `attestation_required` | boolean | プランで制限されます。`true` には Enterprise が必要です。 |
| `aaguid_allowlist`、`aaguid_blocklist` | array of UUID strings | それぞれ一意のエントリーを最大 500 件まで指定できます（エラーは `/settings/<key>/<index>` を指します）。プランで制限されます。空でない一覧には Enterprise が必要です。 |
| `related_origins` | array of strings | `https://host[:port]` 形式のオリジン。プランで制限されます。空でない一覧には Enterprise が必要です。 |
| `passkey_enrollment_prompt` | string | `off` または `after_login`（既定値）。 |

プランで制限されているキーに既定値以外を書き込むと、`403 plan_feature_unavailable` となり、メンバー `feature` と `required_plan` が返されます。プランの権限が利用可能になるまで、これらのキーはどの環境でも設定できません。既定値（`false`、`[]`、`null`）の書き込みやキーの削除は常に許可されます。この機能が利用可能になった後は、`related_origins` の各エントリーが環境の有効な検証済みカスタムドメインである必要があります。そうでない場合、リクエストは `422 related_origin_not_verified` で失敗します。

## エラー

| HTTP | コード | 発生条件 |
|---|---|---|
| 400 | `unknown_field` | ボディに未知のフィールドが含まれています。 |
| 403 | `quota_exceeded` | 環境または組織（`org_id`）の接続数の上限に達しています。 |
| 409 | `conflict` | 同じ `key` または `name` の接続がすでに存在します。 |
| 409 | `connection_test_required` | リクエストが `status: active` の `enterprise` 接続を作成しようとしています。何も書き込まれません。`inactive` で作成し、サインインをテストしてから `:activate` で有効化してください。 |
| 415 | `unsupported_media_type` | コンテンツタイプが `application/json` ではありません。 |
| 422 | `validation_failed` | フィールドが不足しているか無効です。`errors[].pointer` が該当箇所を示します（シークレットのように見える設定の場合は、例えば `/settings/client_secret`）。 |
| 422 | `related_origin_not_verified` | 関連オリジンが環境の検証済みカスタムドメインではありません。 |
| 403 | `plan_feature_unavailable` | 設定した項目がプランに含まれていません（`feature`、`required_plan` のメンバー）。例: `attestation_required`。 |
| 401 | `unauthenticated` | 認証情報が不足しているか、無効または取り消されています。 |
| 403 | `insufficient_permissions` | 認証情報に必要な権限がありません。 |
| 429 | `rate_limited` | レート制限を超えました。`Retry-After` の期間を待ってから再試行してください。 |
| 503 | `service_unavailable` | 依存先が一時的に利用できません。`Retry-After` の期間を待ってから再試行してください。 |

## 例

```bash
curl -X POST https://api.eu.keenauth.com/v1/connections \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key":"google","type":"social","strategy":"google","name":"Google"}'
```