사용자 업데이트

PATCH /v1/users/{user_id} · 권한 users:write

JSON 병합 패치(Content-Type: application/merge-patch+json)로 사용자를 업데이트합니다. 전송한 필드만 변경됩니다. 텍스트 필드는 null 또는 빈 문자열로 지울 수 있으며, email_verified와 phone_verified는 지울 수 없습니다. address는 전체가 교체됩니다. user_metadata와 app_metadata는 키 단위로 병합되며, 값이 null인 키는 삭제됩니다. user_metadata 또는 app_metadata 자체를 null로 보내면 전체가 삭제되고 {}가 남습니다. 상태는 여기서 변경할 수 없으니 차단 및 차단 해제를 사용하십시오. 삭제 대기 중인 사용자는 업데이트할 수 없습니다. If-Match는 선택 사항이며, 전송하는 경우 사용자의 현재 ETag와 일치해야 합니다.

요청

매개변수	위치	필수 여부	설명
`user_id`	path	예	사용자 ID, 접두사 `usr_`.
`If-Match`	header	아니요	이전 읽기에서 받은 `ETag`.

본문은 사용자 생성과 같은 필드를 모두 선택 사항으로 받으며, 아래의 연령 필드를 추가로 받습니다. 알 수 없는 필드는 unknown_field로 거부됩니다.

연령 및 보호자 동의

자체 연령 확인 또는 보호자 동의 절차가 끝나면 그 결과를 아래 필드로 사용자에게 기록하십시오. 이 필드는 모든 사용자 객체에도 반환되며, null은 사용자가 아직 평가되지 않았음을 뜻합니다.

필드	값	참고
`age_group`	`adult`, `minor`, `unknown`	지울 수 없습니다. 연령을 알 수 없으면 `unknown`을 보내십시오.
`parental_consent_status`	`not_required`, `pending`, `granted`, `denied`, `revoked`	`null`이면 지워집니다. `not_required` 이외의 값은 사용자의 `age_group`이 `minor`인 경우에만 허용됩니다.
`age_assurance_level`	`self_declared`, `birthdate_declared`, `third_party_verified`	`null`이면 지워집니다. 절차가 연령을 어느 정도 강도로 확인했는지를 나타냅니다.

age_group 또는 parental_consent_status가 변경되면 user.updated 이벤트가 발생합니다. 이 필드나 메타데이터에 생년월일이나 신분증 번호를 넣지 마십시오. 결과만 전송하십시오.

응답

200 OK. 본문은 사용자 객체입니다. ETag 헤더에는 사용자 버전이 담겨 있습니다.

키에 users:read_pii 권한이 없으면 개인정보가 마스킹됩니다. email은 a***@e***.com이 되고, phone_number는 마지막 2자리만 남습니다(+**********67). name, given_name, family_name, middle_name, nickname은 이니셜(A. L.)이 되며, username은 첫 글자만 남습니다(a***). birthdate는 ****-**-**이 되고, address는 {"redacted": true}가 됩니다. user_metadata와 app_metadata는 마스킹되지 않습니다.

{
  "id": "usr_0a1b2c3d4e5f6g7h8j9k0m1n2p",
  "kind": "regular",
  "status": "active",
  "external_id": null,
  "username": null,
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "email_verified": true,
  "phone_number": null,
  "phone_verified": false,
  "age_group": "adult",
  "parental_consent_status": null,
  "age_assurance_level": "self_declared",
  "user_metadata": {},
  "app_metadata": {},
  "created_via": "admin_api",
  "created_at": "2026-01-15T09:30:00Z",
  "updated_at": "2026-01-15T09:30:00Z",
  "last_sign_in_at": null,
  "deletion_requested_at": null,
  "deletion_due_at": null
}

오류

모든 오류는 안정적인 code를 담은 application/problem+json 본문으로 반환됩니다.

HTTP	`code`	발생 조건
400	`malformed_request`, `unknown_field`	패치가 JSON 객체가 아니거나, 필드가 스키마에 없거나, `If-Match`가 잘못된 형식인 경우.
409	`conflict`	값이 이미 사용 중이거나, 사용자가 삭제 대기 중인 경우(`errors[].code`는 `user_pending_deletion`).
412	`precondition_failed`	`If-Match`가 현재 버전과 일치하지 않는 경우.
415	`unsupported_media_type`	`Content-Type`이 `application/merge-patch+json`이 아닌 경우.
422	`validation_failed`	값이 잘못되었거나 타입이 맞지 않는 경우. `errors[].pointer`가 해당 필드를 가리킵니다.
404	`not_found`	이 환경에 사용자가 없거나 ID 형식이 잘못된 경우.
401	`unauthenticated`	API 키가 없거나, 잘못되었거나, 취소된 경우.
403	`insufficient_permissions`	키에 `users:write` 권한이 없는 경우.
429	`rate_limited`	요청 한도를 초과한 경우. `Retry-After`를 준수하십시오.
503	`service_unavailable`	종속 서비스를 일시적으로 사용할 수 없는 경우. 나중에 다시 시도하십시오.

예시

curl -X PATCH https://api.eu.keenauth.com/v1/users/usr_0a1b2c3d4e5f6g7h8j9k0m1n2p \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{"name": "Ada King", "app_metadata": {"tier": "gold"}}'

미성년자의 승인된 보호자 동의를 기록합니다:

curl -X PATCH https://api.eu.keenauth.com/v1/users/usr_0a1b2c3d4e5f6g7h8j9k0m1n2p \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{"age_group": "minor", "parental_consent_status": "granted", "age_assurance_level": "third_party_verified"}'

개인정보

이 엔드포인트는 개인정보, 즉 최종 사용자 프로필을 포함합니다. KeenAuth API의 개인정보에서 저장되는 항목, 보관 기간, 삭제 방법을 설명합니다. 어떤 필드에도 특수 범주의 개인정보(건강, 생체 정보, 종교, 정치적 견해, 성적 지향)를 보내지 마십시오.