Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/zitadel/zitadel/llms.txt

Use this file to discover all available pages before exploring further.

​
Endpoint

PATCH /v2/users/{user_id}

​
Description

Partially update an existing user. You can change the user’s profile, email, phone, and password. If you change the email or phone, you can specify how the ownership should be verified.

​
Required Permission

  • user.write

​
Path Parameters

​
user_id
string
required
The unique identifier of the user to update.

​
Request Body

​
username
string
New username for the user. Must be unique within the organization.
​
profile
object
Profile information to update (for human users).
​
givenName
string
Updated first name.
​
familyName
string
Updated last name.
​
nickName
string
Updated nickname.
​
displayName
string
Updated display name.
​
preferredLanguage
string
Updated preferred language.
​
gender
string
Updated gender.
​
email
object
Email information to update.
​
email
string
New email address.
​
isVerified
boolean
Whether to mark the email as verified.
​
returnCode
boolean
Return the verification code instead of sending it via email.
​
phone
object
Phone information to update.
​
phone
string
New phone number in E.164 format.
​
isVerified
boolean
Whether to mark the phone as verified.
​
returnCode
boolean
Return the verification code instead of sending it via SMS.
​
password
object
Password information to update.
​
password
string
New password for the user.
​
changeRequired
boolean
Require the user to change the password on next login.

​
Response

​
details
object
Metadata about the update.
​
sequence
string
Sequence number of the change.
​
changeDate
timestamp
Timestamp of when the user was updated.
​
resourceOwner
string
Organization ID that owns the user.
​
emailCode
string
Email verification code if requested.
​
phoneCode
string
Phone verification code if requested.

​
Example Request

curl -X PATCH https://your-domain.zitadel.cloud/v2/users/d654e6ba-70a3-48ef-a95d-37c8d8a7901a \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": {
      "displayName": "Minnie M. Mouse",
      "preferredLanguage": "de"
    },
    "email": {
      "email": "minnie.mouse@example.com",
      "isVerified": false
    }
  }'

​
Example Response

{
  "details": {
    "sequence": "1235",
    "changeDate": "2024-03-15T11:45:00Z",
    "resourceOwner": "69629026806489455"
  }
}

​
Error Responses

  • 404 Not Found - User ID does not exist
  • 409 Conflict - Username already taken
  • 400 Bad Request - Invalid request data
  • 403 Forbidden - Insufficient permissions