# 接続の SP ホストを移行

`POST /v1/connections/{connection_id}:migrate-sp-host` · 権限 `connections:write`

エンタープライズ接続の SP エンドポイント（ACS、メタデータ、シングルログアウト、OIDC コールバック）を新しいホストへ移行し始めます。たとえば `keenauth.app` ホストから、検証済みのカスタムドメインへ移行する場合です。SP の URL は、ID プロバイダがそれらを保持しているため、通常は固定されています。

このリクエストは、接続のステータスに関係なく、種類 `sp_host` の**下書きリビジョン**を作成します。サインインにはまだ何も変更されません。

1. [SP メタデータをダウンロード](sp-metadata.md) と `revision_id` を使用して新しい SP メタデータをダウンロードし、ID プロバイダの管理者に渡します。新しいホストが提供するのは、このメタデータと下書きのテストサインインだけです。
2. `revision_id` を指定して [接続をテスト](test.md) で下書きをテストします。
3. [リビジョンを公開](publish-revision.md) します。接続は新しいホストを使用するようになります。古いホストは、ID プロバイダを更新できるように、さらに 30 日間応答を続け、その後 `404` を返すようになります。

新しい下書きを作成すると、その接続の以前の下書きは破棄されます。このリクエストは `connection.revision_created` として監査されます。

## リクエスト

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `connection_id` | path | はい | エンタープライズ接続 ID（`conn_…`）。 |
| `Idempotency-Key` | header | いいえ | 再試行されたリクエストを安全にするための任意のキー（16〜64 文字）。 |
| `sp_host` | string | はい | 新しいホスト：この環境の有効なホスト（その `keenauth.app` ホスト、または検証済みのカスタムドメイン）。小文字で、ポート番号は含みません。 |

## レスポンス

下書きリビジョンを含む `200 OK`：

```json
{
  "id": "connrev_01j9xr8c2d4e6f8g0h2j4k6m8n",
  "connection_id": "conn_01j9xp6q0r1s5t7v9w1x3y5z7b",
  "protocol": "saml",
  "kind": "sp_host",
  "status": "draft",
  "discard_reason": null,
  "created_at": "2026-10-28T10:00:00Z",
  "decided_at": null,
  "purge_after": null,
  "superseded_revision_id": null,
  "changes": {
    "sp_host": "login.example.com",
    "idp_entity_id": null,
    "idp_sso_url": null,
    "idp_slo_url": null,
    "certificate_fingerprints": [],
    "mfa_authn_context_values": null,
    "issuer": null,
    "client_id": null,
    "client_auth_method": null,
    "provider_profile": null,
    "client_secret_change": null
  },
  "latest_test": null
}
```

`superseded_revision_id` は、このリクエストで破棄された以前の下書きです（ある場合）。

## エラー

| HTTP | code | 発生条件 |
|---|---|---|
| 400 | `unknown_field` | ボディに未知のフィールドが含まれています。 |
| 401 | `unauthenticated` | 認証情報がない、無効、または取り消されています。 |
| 403 | `insufficient_permissions` | 認証情報に `connections:write` がありません。 |
| 404 | `not_found` | 接続がこの環境に存在しない、またはエンタープライズ接続ではありません。 |
| 409 | `conflict` | 以前の SP ホスト移行の 30 日間の期間がまだ終了していない、または接続にまだプロトコル設定がありません。 |
| 422 | `validation_failed` | `errors[]` が `/sp_host` を指し、`required`（必須）、`invalid_value`（小文字のホスト名ではない）、`not_in_environment`（この環境の有効なホストではない）、または `unchanged`（接続の SP ホストと同じ）のいずれかを示します。 |
| 429 | `rate_limited` | レート制限を超えました。`Retry-After` の期間を待ってから再試行してください。 |
| 503 | `service_unavailable` | 依存先が一時的に利用できません。`Retry-After` の期間を待ってから再試行してください。 |

## 例

```bash
curl -X POST "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b:migrate-sp-host" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"sp_host":"login.example.com"}'
```

```bash
keenauth connections migrate-sp-host conn_01j9xp6q0r1s5t7v9w1x3y5z7b --sp-host login.example.com --yes
```