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, all optional, plus the age fields below. Unknown fields are rejected with unknown_field.

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.

{
  "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

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:

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