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: '[email protected]',
is_verified: false
)
)
)
)
response = user_service.create_user(request)
puts "User ID: #{response.user_id}"
The organization where the user will be created
User object containing either human or machine user details
The unique identifier of the created user
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}"
The unique identifier of the user
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: '[email protected]',
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: '[email protected]',
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)
Identity Provider Links
add_idp_link
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_idp_links
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}"
request = Zitadel::Client::UserServiceSetUserMetadataRequest.new(
user_id: 'user_123',
key: 'department',
value: 'Engineering'.bytes
)
response = user_service.set_user_metadata(request)
request = Zitadel::Client::UserServiceListUserMetadataRequest.new(
user_id: 'user_123'
)
response = user_service.list_user_metadata(request)
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: '[email protected]'
)
)
)
)
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
