Skip to main content

Documentation Index

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

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

​
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.
​
user_id
string
Unique identifier of the user
​
details
UserServiceDetails
Metadata about the user resource including sequence number and timestamps
​
state
UserServiceUserState
Current state of the user account (e.g., ACTIVE, INACTIVE, DELETED)
​
username
string
Username of the user, which can be globally unique or unique on organization level
​
login_names
array<string>
List of possible usable login names for the user
​
preferred_login_name
string
Preferred login name of the user
​
human
UserServiceHumanUser
Present if this is a human user. Contains human-specific attributes like profile, email, and phone
​
machine
UserServiceMachineUser
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", "john.doe@example.com"],
  "preferredLoginName": "john.doe@example.com",
  "human": {
    "userId": "123456789",
    "state": "USER_STATE_ACTIVE",
    "username": "john.doe",
    "profile": {
      "givenName": "John",
      "familyName": "Doe",
      "displayName": "John Doe",
      "preferredLanguage": "en"
    },
    "email": {
      "email": "john.doe@example.com",
      "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.
​
user_id
string
Unique identifier of the user
​
state
UserServiceUserState
Current state of the user account
​
username
string
Username of the user, which can be globally unique or unique on organization level
​
login_names
array<string>
Possible usable login names for the user
​
preferred_login_name
string
Preferred login name of the user
​
profile
UserServiceHumanProfile
Profile information including name, gender, and preferred language
​
email
UserServiceHumanEmail
Email address and verification status
​
phone
UserServiceHumanPhone
Phone number and verification status
​
password_change_required
boolean
User is required to change the used password on the next login
​
password_changed
Time
Timestamp when the password was last changed
​
mfa_init_skipped
Time
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
string
Given name (first name) of the user
​
family_name
string
Family name (last name) of the user
​
nick_name
string
Nickname of the user
​
display_name
string
Display name shown in the UI
​
preferred_language
string
Preferred language code (e.g., “en”, “de”, “fr”)
​
gender
UserServiceGender
Gender of the user
​
avatar_url
string
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.
​
email
string
Email address
​
is_verified
boolean
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
string
Phone number in E.164 format
​
is_verified
boolean
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).
​
name
string
Name of the machine user
​
description
string
Description of the machine user’s purpose
​
has_secret
boolean
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

​
Building User Display Information

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
These models are used in conjunction with user models:
  • UserServiceDetails - Resource metadata
  • UserServiceUserState - Enum for user states
  • UserServiceGender - Enum for gender values
  • UserServiceAccessTokenType - Enum for access token types

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us