# 接続を更新

`PATCH /v1/connections/{connection_id}` · 権限 `connections:write`

JSON マージパッチ（`application/merge-patch+json`、RFC 7396）で接続を更新します。`If-Match` は必須です。`key`、`type`、`strategy`、`org_id` は変更できません。何も変更されないパッチでは書き込みは行われず、バージョンも維持されます。設定にシークレットを含めないでください。

## リクエスト

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `connection_id` | string | はい | 接続の ID（`conn_…`）。 |
| `If-Match` | header | はい | 直近に読み取った接続の `ETag`。欠落時は `428`、古い場合は `412`。 |
| `key` | string | いいえ | 変更不可。同じ値は受け付けられます。 |
| `type` | string | いいえ | 変更不可。 |
| `strategy` | string | いいえ | 変更不可。 |
| `name` | string | いいえ | 1〜128 文字。 |
| `display_name` | string \| null | いいえ | `null` を指定するとクリアされます。 |
| `status` | string | いいえ | `active` または `inactive`。 |
| `org_id` | string \| null | いいえ | 変更不可。同じ値は受け付けられます。 |
| `allowed_email_domains` | array of strings \| null | いいえ | リストを置き換えます。`null` または `[]` でクリアされます。作成時と同じルールが適用されます。組織の接続では、新たに追加されたドメインのみが組織の検証済みドメインと照合されます。 |
| `allow_external_domains` | boolean | いいえ | `enterprise` のみ。 |
| `jit_mode` | string | いいえ | `create`、`create_and_update` または `off`。`enterprise` のみ。 |
| `email_trust` | boolean | いいえ | `enterprise` のみ。組織の接続で有効にするには、空でない `allowed_email_domains` が必要で、そのすべてのドメインが組織の検証済みドメインである必要があります。 |
| `default_role_ids` | array of strings \| null | いいえ | リストを置き換えます。`null` または `[]` でクリアされます。作成時と同じルールが適用されます。新たに追加されたロールのみが確認されるため、リスト内に既にあるロールがその後削除されていても、更新はブロックされません（サインイン時にスキップされます）。 |
| `trust_idp_mfa` | boolean | いいえ | `enterprise` のみ。 |
| `settings` | object \| null | いいえ | 再帰的にマージされます（RFC 7396）。`null` のメンバーはそのキーを削除します。`null` を指定するとすべての設定がクリアされます。シークレットは含めないでください。 |

## レスポンス

更新後の接続と新しい `ETag` を含む `200 OK`。

```json
{
  "id": "conn_0k3v8m1q2x9dz4h7s5t6w0y1ab",
  "key": "google",
  "type": "social",
  "strategy": "google",
  "name": "Google",
  "display_name": "Sign in with Google",
  "status": "active",
  "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` で拒否され、`errors[].pointer`（例：`/settings/max_credentials_per_user`）が返されます。`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` で失敗します。設定の検証は、マージパッチが適用された後に、パッチに `settings` が含まれている場合にのみ行われます。

## エラー

| HTTP | code | 発生条件 |
|---|---|---|
| 400 | `unknown_field` | パッチに未知のフィールドまたは読み取り専用のフィールドが含まれています。 |
| 404 | `not_found` | 接続が存在しないか、別の環境に属しています。 |
| 409 | `connection_test_required` | パッチによって `enterprise` の接続が `active` に設定される、または `active` の接続の `allowed_email_domains` にドメインが追加されるが、過去 24 時間以内に結果の構成のテストが成功していない場合（接続を有効化するを参照）。何も書き込まれません。ドメインの削除は確認されません。 |
| 409 | `rp_id_change_requires_migration` | パッチによってパスキー接続の `settings.rp_id` が変更され、その環境に動作しなくなるパスキーがある場合。[パスキーの rpId を変更](change-rp-id.md)を使用してください。何も書き込まれません。 |
| 412 | `precondition_failed` | `If-Match` が現在のバージョンと一致しません。 |
| 415 | `unsupported_media_type` | コンテンツタイプが `application/merge-patch+json` ではありません。 |
| 422 | `validation_failed` | 値が無効か、変更不可のフィールドが変更されました（`code: immutable`）。 |
| 422 | `related_origin_not_verified` | 関連オリジンが環境の検証済みカスタムドメインではありません。 |
| 403 | `plan_feature_unavailable` | プランに設定した機能が含まれていません（`feature`、`required_plan` メンバー）。例：`attestation_required`。 |
| 428 | `precondition_required` | `If-Match` ヘッダーがありません。 |
| 401 | `unauthenticated` | 認証情報がないか、無効または取り消されています。 |
| 403 | `insufficient_permissions` | 認証情報に必要な権限がありません。 |
| 429 | `rate_limited` | レート制限を超えました。`Retry-After` の期間を過ぎてから再試行してください。 |
| 503 | `service_unavailable` | 依存先が一時的に利用できません（例：`rp_id` 変更のパスキーチェックを実行できなかったため、何も書き込まれません）。`Retry-After` の期間を過ぎてから再試行してください。 |

## 例

```bash
curl -X PATCH https://api.eu.keenauth.com/v1/connections/conn_0k3v8m1q2x9dz4h7s5t6w0y1ab \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/merge-patch+json" \
  -H 'If-Match: "1"' \
  -d '{"display_name":"Sign in with Google"}'
```