# 사용자 업데이트

`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`. |

본문은 [사용자 생성](/docs/api/management/users/create)과 같은 필드를 모두 선택 사항으로 받으며, 아래의 연령 필드를 추가로 받습니다. 알 수 없는 필드는 `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`는 마스킹되지 않습니다.

```json
{
  "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` | 종속 서비스를 일시적으로 사용할 수 없는 경우. 나중에 다시 시도하십시오. |

## 예시

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

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

```bash
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의 개인정보](/docs/policies/personal-data)에서 저장되는 항목, 보관 기간, 삭제 방법을 설명합니다. 어떤 필드에도 특수 범주의 개인정보(건강, 생체 정보, 종교, 정치적 견해, 성적 지향)를 보내지 마십시오.