# 연결의 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`는 이 요청으로 폐기된 이전 초안이 있는 경우 해당 초안의 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
```