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.

The User Service provides comprehensive user management capabilities including creating, updating, and deleting users, managing authentication methods, and handling user metadata.

​
Overview

The UserServiceApi class provides methods for:
  • Creating and managing human and machine users
  • Managing authentication factors (passwords, MFA, passkeys, TOTP)
  • Handling identity provider links
  • Managing user keys and tokens
  • User metadata operations
  • User state management (activate, deactivate, lock)

​
Initialization

require 'zitadel/client'

api_client = Zitadel::Client::ApiClient.new
api_client.config.access_token = 'YOUR_ACCESS_TOKEN'

user_service = Zitadel::Client::Api::UserServiceApi.new(api_client)

​
User Management

​
create_user

Create a new human or machine user in the specified organization. 
request = Zitadel::Client::UserServiceCreateUserRequest.new(
  organization_id: 'org_123',
  user: Zitadel::Client::UserServiceUser.new(
    human: Zitadel::Client::UserServiceHuman.new(
      profile: Zitadel::Client::UserServiceSetHumanProfile.new(
        given_name: 'John',
        family_name: 'Doe'
      ),
      email: Zitadel::Client::UserServiceSetHumanEmail.new(
        email: 'john.doe@example.com',
        is_verified: false
      )
    )
  )
)

response = user_service.create_user(request)
puts "User ID: #{response.user_id}"
​
organization_id
string
required
The organization where the user will be created
​
user
UserServiceUser
required
User object containing either human or machine user details
​
user_id
string
The unique identifier of the created user
​
details
UserServiceDetails
Metadata about the creation operation

​
get_user_by_id

Retrieve the full user object (human or machine) including profile, email, and other details. 
request = Zitadel::Client::UserServiceGetUserByIDRequest.new(
  user_id: 'user_123'
)

response = user_service.get_user_by_id(request)
puts "User: #{response.user.inspect}"
​
user_id
string
required
The unique identifier of the user
​
user
UserServiceUser
Complete user object with all details

​
list_users

Search and list users with filtering and pagination. 
request = Zitadel::Client::UserServiceListUsersRequest.new(
  query: Zitadel::Client::UserServiceListQuery.new(
    limit: 50,
    offset: 0
  ),
  queries: [
    Zitadel::Client::UserServiceSearchQuery.new(
      email_query: Zitadel::Client::UserServiceEmailQuery.new(
        email_address: 'john@example.com',
        method: 'CONTAINS'
      )
    )
  ]
)

response = user_service.list_users(request)
response.result.each do |user|
  puts "User: #{user.preferred_login_name}"
end

​
update_user

Update user information. 
request = Zitadel::Client::UserServiceUpdateUserRequest.new(
  user_id: 'user_123',
  human: Zitadel::Client::UserServiceUpdateHumanUser.new(
    profile: Zitadel::Client::UserServiceSetHumanProfile.new(
      given_name: 'Jane',
      family_name: 'Doe'
    )
  )
)

response = user_service.update_user(request)

​
deactivate_user

Deactivate a user account. The user will not be able to log in, but data remains accessible. 
request = Zitadel::Client::UserServiceDeactivateUserRequest.new(
  user_id: 'user_123'
)

response = user_service.deactivate_user(request)

​
reactivate_user

Reactivate a previously deactivated user account. 
request = Zitadel::Client::UserServiceReactivateUserRequest.new(
  user_id: 'user_123'
)

response = user_service.reactivate_user(request)

​
lock_user

Lock a user account, preventing login. 
request = Zitadel::Client::UserServiceLockUserRequest.new(
  user_id: 'user_123'
)

response = user_service.lock_user(request)

​
unlock_user

Unlock a locked user account. 
request = Zitadel::Client::UserServiceUnlockUserRequest.new(
  user_id: 'user_123'
)

response = user_service.unlock_user(request)

​
delete_user

Permanently delete a user. The user will not be able to log in and endpoints will return ‘User not found’. 
request = Zitadel::Client::UserServiceDeleteUserRequest.new(
  user_id: 'user_123'
)

response = user_service.delete_user(request)

​
Authentication Management

​
set_password

Set or update a user’s password. 
request = Zitadel::Client::UserServiceSetPasswordRequest.new(
  user_id: 'user_123',
  new_password: Zitadel::Client::UserServicePassword.new(
    password: 'SecureP@ssw0rd',
    change_required: false
  )
)

response = user_service.set_password(request)

​
password_reset

Initiate a password reset flow for a user. 
request = Zitadel::Client::UserServicePasswordResetRequest.new(
  user_id: 'user_123',
  send_link: Zitadel::Client::UserServiceSendPasswordResetLink.new(
    url_template: 'https://myapp.com/reset?code={{.Code}}'
  )
)

response = user_service.password_reset(request)

​
register_passkey

Register a passkey (WebAuthn) for a user. 
request = Zitadel::Client::UserServiceRegisterPasskeyRequest.new(
  user_id: 'user_123',
  code: Zitadel::Client::UserServicePasskeyRegistrationCode.new(
    code: 'verification_code'
  ),
  authenticator: 'PASSKEY_AUTHENTICATOR_PLATFORM'
)

response = user_service.register_passkey(request)

​
register_totp

Register a TOTP (Time-based One-Time Password) authenticator. 
request = Zitadel::Client::UserServiceRegisterTOTPRequest.new(
  user_id: 'user_123'
)

response = user_service.register_totp(request)
puts "Secret: #{response.secret}"
puts "URI: #{response.uri}"

​
verify_totp_registration

Verify and complete TOTP registration. 
request = Zitadel::Client::UserServiceVerifyTOTPRegistrationRequest.new(
  user_id: 'user_123',
  code: '123456'
)

response = user_service.verify_totp_registration(request)

​
add_otp_email

Add OTP Email as a second factor. 
request = Zitadel::Client::UserServiceAddOTPEmailRequest.new(
  user_id: 'user_123'
)

response = user_service.add_otp_email(request)

​
add_otpsms

Add OTP SMS as a second factor. 
request = Zitadel::Client::UserServiceAddOTPSMSRequest.new(
  user_id: 'user_123'
)

response = user_service.add_otpsms(request)

​
generate_recovery_codes

Generate single-use recovery codes for account recovery. 
request = Zitadel::Client::UserServiceGenerateRecoveryCodesRequest.new(
  user_id: 'user_123'
)

response = user_service.generate_recovery_codes(request)
response.codes.each do |code|
  puts "Recovery code: #{code}"
end

​
list_authentication_factors

List all authentication factors configured for a user. 
request = Zitadel::Client::UserServiceListAuthenticationFactorsRequest.new(
  user_id: 'user_123'
)

response = user_service.list_authentication_factors(request)

​
list_passkeys

List all passkeys registered for a user. 
request = Zitadel::Client::UserServiceListPasskeysRequest.new(
  user_id: 'user_123'
)

response = user_service.list_passkeys(request)

​
Machine User Management

​
add_secret

Generate a client secret for a machine user. 
request = Zitadel::Client::UserServiceAddSecretRequest.new(
  user_id: 'user_123'
)

response = user_service.add_secret(request)
puts "Client ID: #{response.client_id}"
puts "Client Secret: #{response.client_secret}"

​
remove_secret

Remove a client secret from a machine user. 
request = Zitadel::Client::UserServiceRemoveSecretRequest.new(
  user_id: 'user_123'
)

response = user_service.remove_secret(request)

​
add_personal_access_token

Create a Personal Access Token (PAT) for a machine user. 
request = Zitadel::Client::UserServiceAddPersonalAccessTokenRequest.new(
  user_id: 'user_123',
  expiration_date: '2025-12-31T23:59:59Z'
)

response = user_service.add_personal_access_token(request)
puts "Token: #{response.token}"

​
list_personal_access_tokens

List all personal access tokens for a user. 
request = Zitadel::Client::UserServiceListPersonalAccessTokensRequest.new(
  user_id: 'user_123'
)

response = user_service.list_personal_access_tokens(request)

​
add_key

Add a key for JWT profile authentication. 
request = Zitadel::Client::UserServiceAddKeyRequest.new(
  user_id: 'user_123',
  key_type: 'KEY_TYPE_JSON',
  expiration_date: '2025-12-31T23:59:59Z'
)

response = user_service.add_key(request)
puts "Key: #{response.key_details}"

​
list_keys

List all keys for a machine user. 
request = Zitadel::Client::UserServiceListKeysRequest.new(
  user_id: 'user_123'
)

response = user_service.list_keys(request)

​
Email and Phone Management

​
set_email

Set or update a user’s email address. 
request = Zitadel::Client::UserServiceSetEmailRequest.new(
  user_id: 'user_123',
  email: 'newemail@example.com',
  is_verified: false,
  send_code: Zitadel::Client::UserServiceSendEmailVerificationCode.new(
    url_template: 'https://myapp.com/verify?code={{.Code}}'
  )
)

response = user_service.set_email(request)

​
verify_email

Verify a user’s email address. 
request = Zitadel::Client::UserServiceVerifyEmailRequest.new(
  user_id: 'user_123',
  verification_code: 'code_from_email'
)

response = user_service.verify_email(request)

​
set_phone

Set or update a user’s phone number. 
request = Zitadel::Client::UserServiceSetPhoneRequest.new(
  user_id: 'user_123',
  phone: '+1234567890',
  is_verified: false,
  send_code: Zitadel::Client::UserServiceSendPhoneVerificationCode.new
)

response = user_service.set_phone(request)

​
verify_phone

Verify a user’s phone number. 
request = Zitadel::Client::UserServiceVerifyPhoneRequest.new(
  user_id: 'user_123',
  verification_code: 'code_from_sms'
)

response = user_service.verify_phone(request)
Link an external identity provider to a user account. 
request = Zitadel::Client::UserServiceAddIDPLinkRequest.new(
  user_id: 'user_123',
  idp_link: Zitadel::Client::UserServiceIDPLink.new(
    idp_id: 'idp_456',
    user_id: 'external_user_id',
    user_name: 'external_username'
  )
)

response = user_service.add_idp_link(request)
List all identity provider links for a user. 
request = Zitadel::Client::UserServiceListIDPLinksRequest.new(
  user_id: 'user_123'
)

response = user_service.list_idp_links(request)

​
start_identity_provider_intent

Initiate an identity provider authentication flow. 
request = Zitadel::Client::UserServiceStartIdentityProviderIntentRequest.new(
  idp_id: 'idp_456',
  urls: Zitadel::Client::UserServiceRedirectURLs.new(
    success_url: 'https://myapp.com/success',
    failure_url: 'https://myapp.com/failure'
  )
)

response = user_service.start_identity_provider_intent(request)
puts "Auth URL: #{response.auth_url}"

​
User Metadata

​
set_user_metadata

Set or update user metadata. 
request = Zitadel::Client::UserServiceSetUserMetadataRequest.new(
  user_id: 'user_123',
  key: 'department',
  value: 'Engineering'.bytes
)

response = user_service.set_user_metadata(request)

​
list_user_metadata

List all metadata for a user. 
request = Zitadel::Client::UserServiceListUserMetadataRequest.new(
  user_id: 'user_123'
)

response = user_service.list_user_metadata(request)

​
delete_user_metadata

Delete a specific metadata entry. 
request = Zitadel::Client::UserServiceDeleteUserMetadataRequest.new(
  user_id: 'user_123',
  key: 'department'
)

response = user_service.delete_user_metadata(request)

​
User Invitations

​
create_invite_code

Create an invite code for a user to initialize their first authentication method. 
request = Zitadel::Client::UserServiceCreateInviteCodeRequest.new(
  user_id: 'user_123',
  return_code: true,
  url_template: 'https://myapp.com/invite?code={{.Code}}',
  application_name: 'My Application'
)

response = user_service.create_invite_code(request)
puts "Invite code: #{response.code}"

​
resend_invite_code

Resend an existing invite code to a user. 
request = Zitadel::Client::UserServiceResendInviteCodeRequest.new(
  user_id: 'user_123'
)

response = user_service.resend_invite_code(request)

​
verify_invite_code

Verify an invite code. 
request = Zitadel::Client::UserServiceVerifyInviteCodeRequest.new(
  user_id: 'user_123',
  invite_code: 'code_from_email'
)

response = user_service.verify_invite_code(request)

​
Error Handling

begin
  response = user_service.get_user_by_id(request)
rescue Zitadel::Client::ApiError => e
  puts "Error: #{e.message}"
  puts "Status code: #{e.code}"
  puts "Response body: #{e.response_body}"
end

​
Complete Example

require 'zitadel/client'

# Initialize client
api_client = Zitadel::Client::ApiClient.new
api_client.config.access_token = ENV['ZITADEL_ACCESS_TOKEN']

user_service = Zitadel::Client::Api::UserServiceApi.new(api_client)

begin
  # Create a new user
  create_request = Zitadel::Client::UserServiceCreateUserRequest.new(
    organization_id: 'org_123',
    user: Zitadel::Client::UserServiceUser.new(
      human: Zitadel::Client::UserServiceHuman.new(
        profile: Zitadel::Client::UserServiceSetHumanProfile.new(
          given_name: 'John',
          family_name: 'Doe'
        ),
        email: Zitadel::Client::UserServiceSetHumanEmail.new(
          email: 'john.doe@example.com'
        )
      )
    )
  )
  
  user_response = user_service.create_user(create_request)
  user_id = user_response.user_id
  puts "Created user: #{user_id}"
  
  # Set password
  password_request = Zitadel::Client::UserServiceSetPasswordRequest.new(
    user_id: user_id,
    new_password: Zitadel::Client::UserServicePassword.new(
      password: 'SecureP@ssw0rd123'
    )
  )
  user_service.set_password(password_request)
  puts "Password set successfully"
  
  # Register TOTP
  totp_request = Zitadel::Client::UserServiceRegisterTOTPRequest.new(
    user_id: user_id
  )
  totp_response = user_service.register_totp(totp_request)
  puts "TOTP URI: #{totp_response.uri}"
  
rescue Zitadel::Client::ApiError => e
  puts "Error: #{e.message}"
end

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us