연결 업데이트

PATCH /v1/connections/{connection_id} · 권한 connections:write

JSON 병합 패치(application/merge-patch+json, RFC 7396)로 연결을 업데이트합니다. If-Match가 필요합니다. key, type, strategy, org_id는 변경할 수 없습니다. 변경 사항이 없는 패치는 아무것도 기록하지 않으며 버전을 유지합니다. 설정에 비밀 값을 포함하지 마십시오.

요청

필드 유형 필수 설명
connection_id string 예 연결 식별자(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를 반환합니다.

{
  "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와 /settings/max_credentials_per_user 같은 errors[].pointer로 거부됩니다. null 값은 기본값을 의미합니다. 형식 오류는 계획 오류보다 먼저 보고됩니다.

키 유형 참고
rp_id string 없음, null 또는 빈 값이면 각 로그인 호스트가 자체 rpId가 됩니다. 그렇지 않으면 환경의 active 상태인 사용자 지정 도메인의 호스트 이름(소문자, IDNA A-label)이어야 하며, 그 밖의 값은 422 validation_failed(/settings/rp_id)입니다. 환경에 패스키가 이미 있으면 패스키 rpId 변경을 사용하여 변경하십시오.
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] 형식의 origin. 요금제 제한: 비어 있지 않은 목록은 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 변경을 사용하십시오. 아무것도 기록되지 않습니다.
412 precondition_failed If-Match가 현재 버전과 일치하지 않습니다.
415 unsupported_media_type 콘텐츠 유형이 application/merge-patch+json이 아닙니다.
422 validation_failed 값이 잘못되었거나 변경할 수 없는 필드가 변경되었습니다(code: immutable).
422 related_origin_not_verified 관련 origin이 환경의 확인된 사용자 지정 도메인이 아닙니다.
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 기간 이후에 다시 시도하십시오.

예시

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