Update a user (admin)

PATCH/v1/admin/orgs/{slug}/users/{id}

Partially updates a user: any of email, username, attributes. Omitted fields are left unchanged; attributes, when present, REPLACES the whole stored map. The password is not changed here (use the password sub-resource). Requires the users.update permission. The id must belong to slug's organization; one that belongs to another is answered as 404, exactly like an id that does not exist. A change of email or username is refused 403 protected_account for the caller's own account and for an account that is more privileged than the caller; a privileged account needs a caller holding roles.assign as well.

PATCH/v1/admin/orgs/{slug}/users/{id}

curl -g -X PATCH 'https://auth.example.com/v1/admin/orgs/{slug}/users/{id}' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

200 OK

{
  "id": "3f1a5b2c-8d4e-4f6a-9b0c-1d2e3f4a5b6c",
  "username": "alice@example.com",
  "email": "alice@example.com",
  "password_set": false,
  "invitation_pending": false,
  "failed_login_attempts": 0,
  "status": "active",
  "created_at": "2026-01-15T09:30:00Z",
  "updated_at": "2026-01-15T09:30:00Z"
}

Authorization

Bearer tokenOAuth 2.0nauthera.users:write

The access token must carry the scope shown.

Send it in the Authorization header:

The access token, as Bearer <token> (RFC 6750 §2.1) or, for a sender-constrained token, DPoP <token> (RFC 9449 §7.1). A token minted with a cnf.jkt confirmation is only accepted together with a DPoP proof signed by that key, whichever of the two schemes carries it.

The caller must also hold the permission users.update: Change a user's email address, username and attributes.

Path parameters

slugstringrequired
The organization slug. It names the TENANT OF RECORD for the operation: the rows it reads and writes, the policy its secrets are derived under, and the organization its audit record is filed against all come from this organization. A token is admitted only through its own slug, except a main-org token, which may be admitted through any — so cross-tenant administration is performed through the TARGET tenant's slug, never by naming its resources through another. A token reaching for a slug it may not be admitted through is refused identically whether that organization exists or not.
1–64 characters
idstringrequired
The user id (UUID).
1–64 characters

Headers

DPoPstring
DPoP proof JWT (RFC 9449 §4). REQUIRED on a request presenting a DPoP-bound access token, and it must be signed by the key named in the token's cnf.jkt and cover this request's method and URI. The proof is read from the request itself rather than from this decoded parameter, so every protected operation is covered whether or not it declares it.

Request body

application/json

A partial update of a user. Every field is optional; omitted fields are left unchanged. attributes, when present, REPLACES the whole stored map. The password is not settable here (use the password sub-resource). Changing email leaves the new address unverified unless email_verified is sent as true.

emailstring · email
at most 320 characters
usernamestring
1–320 characters
email_verifiedboolean
Mark the user's address, after any change above, verified or not.
attributesmap of strings

No other properties are accepted.

Responses

200 OKapplication/jsonThe updated user.
The updated user.
Headers
- Cache-Controlno-store
Body
A local user as seen by the admin API. The argon2id password hash is NEVER included. attributes is the free-form string map stored on the identity (e.g. the display "name"). The nullable timestamps (locked_until, last_login_at) are omitted when unset. Admin access is not a property of the user: it follows the roles the user is granted in an organization (e.g. org-user-admin), which are resolved on every admin request.
- idstringrequired
  The user id (UUID).
  Example"3f1a5b2c-8d4e-4f6a-9b0c-1d2e3f4a5b6c"
- usernamestringrequired
  Example"alice@example.com"
- emailstringrequired
  Example"alice@example.com"
- password_setbooleanrequired
  Whether the user has a password. An invited user has none until they accept the invitation, and an account an identity provider created has none at all.
- invitation_pendingbooleanrequired
  Whether the user still waits on an invitation: they have no password and no linked identity provider account to sign in with.
- failed_login_attemptsintegerrequired
  Consecutive failed password verifications since the last success.
- statusenumrequired
  What an administrator decided about an account, separate from the automatic lock after repeated wrong passwords. active may sign in; suspended may not until it is reactivated or its suspended_until passes, after which it reads active again with no write in between; blocked may not until it is reactivated. A suspended or blocked account can neither sign in nor obtain or renew a token through any grant. Translated under vocabulary.UserAccountStatus.<value>. Compatibility: closed. A client should render a value it does not know as unavailable rather than active.
  Possible values"active""suspended""blocked"
- created_atstring · date-timerequired
- updated_atstring · date-timerequired
- email_verified_atstring · date-time
  When email was proven to be the user's (RFC3339); omitted while it has not been. It is released as the email_verified claim, and a change of address clears it.
- attributesmap of strings
  Free-form string attributes stored on the identity.
- locked_untilstring · date-time
  Soft-lock deadline (RFC3339); omitted when the account is not locked.
- last_login_atstring · date-time
  Last successful sign-in (RFC3339); omitted when the user has never signed in.
- status_reasonstring
  The administrator's note on the current status; omitted when there is none.
- suspended_untilstring · date-time
  When a suspension lifts by itself (RFC3339); omitted when the account is not suspended or the suspension has no end.
- status_changed_atstring · date-time
  When the status last changed (RFC3339); omitted when it never has.
401 Unauthorizedapplication/problem+jsonProblem details (RFC 9457) with an RFC 6750 / RFC 9449 challenge.
Problem details (RFC 9457) with an RFC 6750 / RFC 9449 challenge.
Headers
- Cache-Controlno-store
- WWW-Authenticatestring
- DPoP-Noncestring
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json). code is a stable machine-readable slug for the problem kind (it mirrors the suffix of type), so consumers can branch on it without parsing prose. errors is present on validation failures and lists every offending field.
- titlestringrequired
  Example"Request validation failed"
- statusintegerrequired
  Example400
- typestring · uri
  Example"urn:problem-type:validation_error"
- detailstring
  Example"One or more fields did not satisfy the API schema."
- codeenum
  The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing title or detail, which are English prose for logs. A problem whose status says everything the server knows carries no code.
  Show moreShow less
  validation_error is the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are the errors list — one entry per offending field — which a form renders on those fields. required and malformed are spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.
  
  Compatibility: this is a CLOSED enum, with the same cost as AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.
  Possible values"invalid_request""invalid_credentials""forbidden""unauthorized""insufficient_user_authentication""protected_account""last_role_administrator""invalid_code""too_many_requests""too_many_attempts""account_locked""account_unavailable""already_enrolled""registration_disabled""registration_conflict""captcha_failed""invalid_reset_link""invalid_verification_link""invalid_invitation_link""mail_relay_missing""not_found""conflict""unavailable""busy""window_too_large""too_many_series""internal_error""rate_limited""malformed""body_too_large""required""validation_error""unknown_org""invalid_token""invalid_dpop_proof""use_dpop_nonce""server_error"
- instancestring
  Example"/introspect"
- request_idstring
  Example"8d94ed49-1caf-4ab3-9594-557142f2d023"
- trace_idstring
  Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
  Example"4bf92f3577b34da6a3ce929d0e0e4736"
- errorsarray of objects
  Field-level violations (present for validation errors).
  Each item:
  A single field-level validation violation.
  Show item attributesHide item attributes
  fieldstringrequired
  Offending field, dotted for nested bodies (e.g. child.id).
  Example"token_type_hint"
  codestringrequired
  Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
  Example"not_allowed"
  messagestringrequired
  Example"field token_type_hint must be one of [access_token, refresh_token]"
403 Forbiddenapplication/problem+jsonProblem details (RFC 9457) with an RFC 6750 / RFC 9449 challenge.
Problem details (RFC 9457) with an RFC 6750 / RFC 9449 challenge.
Headers
- Cache-Controlno-store
- WWW-Authenticatestring
- DPoP-Noncestring
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json). code is a stable machine-readable slug for the problem kind (it mirrors the suffix of type), so consumers can branch on it without parsing prose. errors is present on validation failures and lists every offending field.
- titlestringrequired
  Example"Request validation failed"
- statusintegerrequired
  Example400
- typestring · uri
  Example"urn:problem-type:validation_error"
- detailstring
  Example"One or more fields did not satisfy the API schema."
- codeenum
  The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing title or detail, which are English prose for logs. A problem whose status says everything the server knows carries no code.
  Show moreShow less
  validation_error is the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are the errors list — one entry per offending field — which a form renders on those fields. required and malformed are spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.
  
  Compatibility: this is a CLOSED enum, with the same cost as AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.
  Possible values"invalid_request""invalid_credentials""forbidden""unauthorized""insufficient_user_authentication""protected_account""last_role_administrator""invalid_code""too_many_requests""too_many_attempts""account_locked""account_unavailable""already_enrolled""registration_disabled""registration_conflict""captcha_failed""invalid_reset_link""invalid_verification_link""invalid_invitation_link""mail_relay_missing""not_found""conflict""unavailable""busy""window_too_large""too_many_series""internal_error""rate_limited""malformed""body_too_large""required""validation_error""unknown_org""invalid_token""invalid_dpop_proof""use_dpop_nonce""server_error"
- instancestring
  Example"/introspect"
- request_idstring
  Example"8d94ed49-1caf-4ab3-9594-557142f2d023"
- trace_idstring
  Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
  Example"4bf92f3577b34da6a3ce929d0e0e4736"
- errorsarray of objects
  Field-level violations (present for validation errors).
  Each item:
  A single field-level validation violation.
  Show item attributesHide item attributes
  fieldstringrequired
  Offending field, dotted for nested bodies (e.g. child.id).
  Example"token_type_hint"
  codestringrequired
  Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
  Example"not_allowed"
  messagestringrequired
  Example"field token_type_hint must be one of [access_token, refresh_token]"
404 Not Foundapplication/problem+jsonProblem details (RFC 9457).
Problem details (RFC 9457).
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json). code is a stable machine-readable slug for the problem kind (it mirrors the suffix of type), so consumers can branch on it without parsing prose. errors is present on validation failures and lists every offending field.
- titlestringrequired
  Example"Request validation failed"
- statusintegerrequired
  Example400
- typestring · uri
  Example"urn:problem-type:validation_error"
- detailstring
  Example"One or more fields did not satisfy the API schema."
- codeenum
  The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing title or detail, which are English prose for logs. A problem whose status says everything the server knows carries no code.
  Show moreShow less
  validation_error is the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are the errors list — one entry per offending field — which a form renders on those fields. required and malformed are spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.
  
  Compatibility: this is a CLOSED enum, with the same cost as AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.
  Possible values"invalid_request""invalid_credentials""forbidden""unauthorized""insufficient_user_authentication""protected_account""last_role_administrator""invalid_code""too_many_requests""too_many_attempts""account_locked""account_unavailable""already_enrolled""registration_disabled""registration_conflict""captcha_failed""invalid_reset_link""invalid_verification_link""invalid_invitation_link""mail_relay_missing""not_found""conflict""unavailable""busy""window_too_large""too_many_series""internal_error""rate_limited""malformed""body_too_large""required""validation_error""unknown_org""invalid_token""invalid_dpop_proof""use_dpop_nonce""server_error"
- instancestring
  Example"/introspect"
- request_idstring
  Example"8d94ed49-1caf-4ab3-9594-557142f2d023"
- trace_idstring
  Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
  Example"4bf92f3577b34da6a3ce929d0e0e4736"
- errorsarray of objects
  Field-level violations (present for validation errors).
  Each item:
  A single field-level validation violation.
  Show item attributesHide item attributes
  fieldstringrequired
  Offending field, dotted for nested bodies (e.g. child.id).
  Example"token_type_hint"
  codestringrequired
  Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
  Example"not_allowed"
  messagestringrequired
  Example"field token_type_hint must be one of [access_token, refresh_token]"
409 Conflictapplication/problem+jsonProblem details (RFC 9457).
Problem details (RFC 9457).
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json). code is a stable machine-readable slug for the problem kind (it mirrors the suffix of type), so consumers can branch on it without parsing prose. errors is present on validation failures and lists every offending field.
- titlestringrequired
  Example"Request validation failed"
- statusintegerrequired
  Example400
- typestring · uri
  Example"urn:problem-type:validation_error"
- detailstring
  Example"One or more fields did not satisfy the API schema."
- codeenum
  The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing title or detail, which are English prose for logs. A problem whose status says everything the server knows carries no code.
  Show moreShow less
  validation_error is the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are the errors list — one entry per offending field — which a form renders on those fields. required and malformed are spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.
  
  Compatibility: this is a CLOSED enum, with the same cost as AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.
  Possible values"invalid_request""invalid_credentials""forbidden""unauthorized""insufficient_user_authentication""protected_account""last_role_administrator""invalid_code""too_many_requests""too_many_attempts""account_locked""account_unavailable""already_enrolled""registration_disabled""registration_conflict""captcha_failed""invalid_reset_link""invalid_verification_link""invalid_invitation_link""mail_relay_missing""not_found""conflict""unavailable""busy""window_too_large""too_many_series""internal_error""rate_limited""malformed""body_too_large""required""validation_error""unknown_org""invalid_token""invalid_dpop_proof""use_dpop_nonce""server_error"
- instancestring
  Example"/introspect"
- request_idstring
  Example"8d94ed49-1caf-4ab3-9594-557142f2d023"
- trace_idstring
  Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
  Example"4bf92f3577b34da6a3ce929d0e0e4736"
- errorsarray of objects
  Field-level violations (present for validation errors).
  Each item:
  A single field-level validation violation.
  Show item attributesHide item attributes
  fieldstringrequired
  Offending field, dotted for nested bodies (e.g. child.id).
  Example"token_type_hint"
  codestringrequired
  Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
  Example"not_allowed"
  messagestringrequired
  Example"field token_type_hint must be one of [access_token, refresh_token]"
429 Too Many Requestsapplication/problem+jsonToo many requests.
Too many requests.
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json). code is a stable machine-readable slug for the problem kind (it mirrors the suffix of type), so consumers can branch on it without parsing prose. errors is present on validation failures and lists every offending field.
- titlestringrequired
  Example"Request validation failed"
- statusintegerrequired
  Example400
- typestring · uri
  Example"urn:problem-type:validation_error"
- detailstring
  Example"One or more fields did not satisfy the API schema."
- codeenum
  The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing title or detail, which are English prose for logs. A problem whose status says everything the server knows carries no code.
  Show moreShow less
  validation_error is the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are the errors list — one entry per offending field — which a form renders on those fields. required and malformed are spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.
  
  Compatibility: this is a CLOSED enum, with the same cost as AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.
  Possible values"invalid_request""invalid_credentials""forbidden""unauthorized""insufficient_user_authentication""protected_account""last_role_administrator""invalid_code""too_many_requests""too_many_attempts""account_locked""account_unavailable""already_enrolled""registration_disabled""registration_conflict""captcha_failed""invalid_reset_link""invalid_verification_link""invalid_invitation_link""mail_relay_missing""not_found""conflict""unavailable""busy""window_too_large""too_many_series""internal_error""rate_limited""malformed""body_too_large""required""validation_error""unknown_org""invalid_token""invalid_dpop_proof""use_dpop_nonce""server_error"
- instancestring
  Example"/introspect"
- request_idstring
  Example"8d94ed49-1caf-4ab3-9594-557142f2d023"
- trace_idstring
  Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
  Example"4bf92f3577b34da6a3ce929d0e0e4736"
- errorsarray of objects
  Field-level violations (present for validation errors).
  Each item:
  A single field-level validation violation.
  Show item attributesHide item attributes
  fieldstringrequired
  Offending field, dotted for nested bodies (e.g. child.id).
  Example"token_type_hint"
  codestringrequired
  Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
  Example"not_allowed"
  messagestringrequired
  Example"field token_type_hint must be one of [access_token, refresh_token]"
Errorapplication/problem+jsonProblem details (RFC 9457) with an RFC 6750 / RFC 9449 challenge.
Problem details (RFC 9457) with an RFC 6750 / RFC 9449 challenge.
Headers
- Cache-Controlno-store
- WWW-Authenticatestring
- DPoP-Noncestring
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json). code is a stable machine-readable slug for the problem kind (it mirrors the suffix of type), so consumers can branch on it without parsing prose. errors is present on validation failures and lists every offending field.
- titlestringrequired
  Example"Request validation failed"
- statusintegerrequired
  Example400
- typestring · uri
  Example"urn:problem-type:validation_error"
- detailstring
  Example"One or more fields did not satisfy the API schema."
- codeenum
  The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing title or detail, which are English prose for logs. A problem whose status says everything the server knows carries no code.
  Show moreShow less
  validation_error is the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are the errors list — one entry per offending field — which a form renders on those fields. required and malformed are spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.
  
  Compatibility: this is a CLOSED enum, with the same cost as AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.
  Possible values"invalid_request""invalid_credentials""forbidden""unauthorized""insufficient_user_authentication""protected_account""last_role_administrator""invalid_code""too_many_requests""too_many_attempts""account_locked""account_unavailable""already_enrolled""registration_disabled""registration_conflict""captcha_failed""invalid_reset_link""invalid_verification_link""invalid_invitation_link""mail_relay_missing""not_found""conflict""unavailable""busy""window_too_large""too_many_series""internal_error""rate_limited""malformed""body_too_large""required""validation_error""unknown_org""invalid_token""invalid_dpop_proof""use_dpop_nonce""server_error"
- instancestring
  Example"/introspect"
- request_idstring
  Example"8d94ed49-1caf-4ab3-9594-557142f2d023"
- trace_idstring
  Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
  Example"4bf92f3577b34da6a3ce929d0e0e4736"
- errorsarray of objects
  Field-level violations (present for validation errors).
  Each item:
  A single field-level validation violation.
  Show item attributesHide item attributes
  fieldstringrequired
  Offending field, dotted for nested bodies (e.g. child.id).
  Example"token_type_hint"
  codestringrequired
  Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
  Example"not_allowed"
  messagestringrequired
  Example"field token_type_hint must be one of [access_token, refresh_token]"

PreviousGet a user NextDelete a user

Update a user (admin)

PATCH/v1/admin/orgs/{slug}/users/{id}

Headers

Body

Headers

Body

Headers

Body

Body

Body

Body

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Body

Body

Body

Headers

Body