연결의 SP 호스트 마이그레이션

POST /v1/connections/{connection_id}:migrate-sp-host · 권한 connections:write

엔터프라이즈 연결의 SP 엔드포인트(ACS, 메타데이터, 단일 로그아웃, OIDC 콜백)를 새 호스트로 이전을 시작합니다. 예를 들어 keenauth.app 호스트에서 확인된 사용자 지정 도메인으로 이전할 수 있습니다. SP URL은 ID 공급자가 이를 보유하고 있으므로 그 외에는 고정되어 있습니다.

이 요청은 연결의 상태와 관계없이 sp_host 유형의 초안 리비전을 생성합니다. 아직 로그인에는 아무 변경도 없습니다.

SP 메타데이터 다운로드와 revision_id로 새 SP 메타데이터를 다운로드하고, ID 공급자 관리자에게 전달하십시오. 새 호스트는 이 메타데이터와 초안의 테스트 로그인만 제공하며, 그 외에는 제공하지 않습니다.
revision_id와 함께 연결 테스트로 초안을 테스트하십시오.
리비전을 게시하십시오. 이제 연결은 새 호스트를 사용합니다. 이전 호스트는 ID 공급자를 업데이트할 수 있도록 30일 더 응답하며, 그 후에는 404를 반환합니다.

새 초안을 만들면 연결의 이전 초안은 폐기됩니다. 이 요청은 connection.revision_created로 감사됩니다.

요청

필드	유형	필수	설명
`connection_id`	path	예	엔터프라이즈 연결 ID(`conn_…`).
`Idempotency-Key`	header	아니요	재시도한 요청을 안전하게 만드는 선택적 키(16~64자).
`sp_host`	string	예	새 호스트입니다. 이 환경의 활성 호스트(`keenauth.app` 호스트 또는 확인된 사용자 지정 도메인)여야 하며, 소문자이고 포트가 없어야 합니다.

응답

초안 리비전과 함께 200 OK를 반환합니다.

{
  "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` 기간 이후에 다시 시도하십시오.

예제

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"}'

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