Overview
User models represent user entities and their associated data in Zitadel. The SDK distinguishes between human users (actual people) and machine users (service accounts).
UserServiceUser
The main user model that can represent either a human or machine user.
Unique identifier of the user
Metadata about the user resource including sequence number and timestamps
Current state of the user account (e.g., ACTIVE, INACTIVE, DELETED)
Username of the user, which can be globally unique or unique on organization level
List of possible usable login names for the user
Preferred login name of the user
Present if this is a human user. Contains human-specific attributes like profile, email, and phone
Present if this is a machine user. Contains machine-specific attributes
Example JSON
{
"userId": "123456789",
"state": "USER_STATE_ACTIVE",
"username": "john.doe",
"loginNames": ["john.doe", "[email protected]"],
"preferredLoginName": "[email protected]",
"human": {
"userId": "123456789",
"state": "USER_STATE_ACTIVE",
"username": "john.doe",
"profile": {
"givenName": "John",
"familyName": "Doe",
"displayName": "John Doe",
"preferredLanguage": "en"
},
"email": {
"email": "[email protected]",
"isVerified": true
}
}
}
Example Usage
# Access user information
user = response.user
if user.human
puts "Human User: #{user.username}"
puts "Email: #{user.human.email.email}"
puts "Name: #{user.human.profile.given_name} #{user.human.profile.family_name}"
elsif user.machine
puts "Machine User: #{user.machine.name}"
puts "Description: #{user.machine.description}"
end
UserServiceHumanUser
Represents a human user with personal information.
Unique identifier of the user
Current state of the user account
Username of the user, which can be globally unique or unique on organization level
Possible usable login names for the user
Preferred login name of the user
Profile information including name, gender, and preferred language
Email address and verification status
Phone number and verification status
User is required to change the used password on the next login
Timestamp when the password was last changed
Timestamp when MFA initialization was skipped
Example Usage
human_user = user.human
# Access profile
profile = human_user.profile
puts "Name: #{profile.given_name} #{profile.family_name}"
puts "Display Name: #{profile.display_name}"
puts "Language: #{profile.preferred_language}"
# Check email verification
if human_user.email&.is_verified
puts "Verified email: #{human_user.email.email}"
else
puts "Email not verified"
end
# Check password status
if human_user.password_change_required
puts "Password change required"
end
UserServiceHumanProfile
Contains profile information for a human user.
Given name (first name) of the user
Family name (last name) of the user
Display name shown in the UI
Preferred language code (e.g., “en”, “de”, “fr”)
URL to the user’s avatar image
Example Usage
profile = human_user.profile
# Build full name
full_name = "#{profile.given_name} #{profile.family_name}"
# Use display name if available, otherwise full name
display = profile.display_name || full_name
puts "Welcome, #{display}!"
UserServiceHumanEmail
Represents email information for a human user.
Whether the email address has been verified
Example Usage
email = human_user.email
if email
puts "Email: #{email.email}"
puts "Status: #{email.is_verified ? 'Verified' : 'Not Verified'}"
unless email.is_verified
# Trigger email verification
puts "Please verify your email address"
end
end
UserServiceHumanPhone
Represents phone information for a human user.
Phone number in E.164 format
Whether the phone number has been verified
Example Usage
phone = human_user.phone
if phone
puts "Phone: #{phone.phone}"
puts "Status: #{phone.is_verified ? 'Verified' : 'Not Verified'}"
end
UserServiceMachineUser
Represents a machine user (service account).
Description of the machine user’s purpose
Whether the machine user has a client secret configured
access_token_type
UserServiceAccessTokenType
Type of access token used by this machine user (e.g., JWT or Bearer)
Example JSON
{
"name": "api-service-account",
"description": "Service account for API integration",
"hasSecret": true,
"accessTokenType": "ACCESS_TOKEN_TYPE_JWT"
}
Example Usage
machine_user = user.machine
if machine_user
puts "Machine User: #{machine_user.name}"
puts "Description: #{machine_user.description}"
puts "Has Secret: #{machine_user.has_secret}"
puts "Token Type: #{machine_user.access_token_type}"
end
Common User Patterns
Checking User Type
user = response.user
case
when user.human
handle_human_user(user.human)
when user.machine
handle_machine_user(user.machine)
else
puts "Unknown user type"
end
def get_user_display_info(user)
return user.machine.name if user.machine
if user.human&.profile
profile = user.human.profile
profile.display_name || "#{profile.given_name} #{profile.family_name}"
else
user.username
end
end
puts "User: #{get_user_display_info(user)}"
Validating User Status
def user_can_login?(user)
return false unless user.state == 'USER_STATE_ACTIVE'
if user.human
# Check if email is verified (if required by your policy)
return false unless user.human.email&.is_verified
# Check if password change is required
return false if user.human.password_change_required
end
true
end
if user_can_login?(user)
puts "User can log in"
else
puts "User cannot log in"
end
UserServiceDetails - Resource metadataUserServiceUserState - Enum for user statesUserServiceGender - Enum for gender valuesUserServiceAccessTokenType - Enum for access token types
Next Steps
