# Update a user

`PATCH /v1/users/{user_id}` · permission `users:write`

Updates a user with a JSON merge patch (`Content-Type: application/merge-patch+json`). Only the fields you send change. Text fields are cleared with `null` or an empty string; `email_verified` and `phone_verified` cannot be cleared; `address` is replaced as a whole; `user_metadata` and `app_metadata` are merged key by key and a `null` value deletes that key; sending `user_metadata` or `app_metadata` itself as `null` deletes all of it and leaves `{}`. The status cannot be changed here; use block and unblock. A user that is pending deletion cannot be updated. `If-Match` is optional: when sent it must match the user's current `ETag`.

## Request

| Parameter | In | Required | Description |
|---|---|---|---|
| `user_id` | path | yes | User id, prefixed `usr_`. |
| `If-Match` | header | no | The `ETag` from a previous read. |

The body accepts the same fields as [Create a user](/docs/api/management/users/create), all optional, plus the age fields below. Unknown fields are rejected with `unknown_field`.

### Age and parental consent

When your own age verification or parental consent process finishes, record its result on the user with these fields. They are also returned on every user object; `null` means the user has not been evaluated.

| Field | Values | Notes |
|---|---|---|
| `age_group` | `adult`, `minor`, `unknown` | Cannot be cleared; send `unknown` when the age is not known. |
| `parental_consent_status` | `not_required`, `pending`, `granted`, `denied`, `revoked` | `null` clears it. Any value other than `not_required` is accepted only when the user's `age_group` is `minor`. |
| `age_assurance_level` | `self_declared`, `birthdate_declared`, `third_party_verified` | `null` clears it. How strongly your process established the age. |

A change to `age_group` or `parental_consent_status` emits a `user.updated` event. Do not put a birth date or an identity document number in these fields or in metadata to support them; send only the result.

## Response

`200 OK`. The body is the user object. The `ETag` header carries the user version.

Personal data is masked when the key lacks the `users:read_pii` permission: `email` becomes `a***@e***.com`, `phone_number` keeps only its last 2 digits (`+**********67`), `name`, `given_name`, `family_name`, `middle_name` and `nickname` become initials (`A. L.`), `username` keeps only its first character (`a***`), `birthdate` becomes `****-**-**` and `address` becomes `{"redacted": true}`. `user_metadata` and `app_metadata` are not masked.

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

## Errors

Every error is an `application/problem+json` body with a stable `code`.

| HTTP | `code` | When |
|---|---|---|
| 400 | `malformed_request`, `unknown_field` | The patch is not a JSON object, or a field is not in the schema; or `If-Match` is malformed. |
| 409 | `conflict` | The value is already in use, or the user is pending deletion (`errors[].code` is `user_pending_deletion`). |
| 412 | `precondition_failed` | `If-Match` does not match the current version. |
| 415 | `unsupported_media_type` | `Content-Type` is not `application/merge-patch+json`. |
| 422 | `validation_failed` | A value is invalid or has the wrong type; `errors[].pointer` names the field. |
| 404 | `not_found` | The user does not exist in this environment (or the id is malformed). |
| 401 | `unauthenticated` | The API key is missing, invalid or revoked. |
| 403 | `insufficient_permissions` | The key lacks the `users:write` permission. |
| 429 | `rate_limited` | The rate limit was exceeded; honor `Retry-After`. |
| 503 | `service_unavailable` | A dependency is temporarily unavailable; retry later. |

## Example

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

Record a granted parental consent for a minor:

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

## Personal data

This endpoint carries personal data: end-user profile. [Personal data in the KeenAuth APIs](/docs/policies/personal-data) describes what is stored, how long it is kept and how it is deleted. Do not send special categories of personal data (health, biometric data, religion, political opinions, sexual orientation) in any field.