This is a beta API. Please migrate to the User Service endpoints. These beta endpoints will be removed in the next major version of ZITADEL. Overview
The Beta User Service provides endpoints for managing user accounts, profiles, multi-factor authentication, and user lifecycle operations.
Class
Zitadel::Client::Api::BetaUserServiceApi
Methods
add_human_user
Create or import a new human user.
add_human_user(beta_user_service_add_human_user_request, opts = {})
beta_user_service_add_human_user_request
BetaUserServiceAddHumanUserRequest
required
Request object containing user details including username, profile, email, and optional password.
Optional parameters for the request.
BetaUserServiceAddHumanUserResponse
Example:
user_service = Zitadel::Client::Api::BetaUserServiceApi.new
request = Zitadel::Client::BetaUserServiceAddHumanUserRequest.new(
username: '[email protected]',
profile: {
first_name: 'Jane',
last_name: 'Doe',
display_name: 'Jane Doe'
},
email: {
email: '[email protected]',
is_verified: false
},
password: 'SecureP@ssw0rd!'
)
response = user_service.add_human_user(request)
puts "User ID: #{response.user_id}"
add_idp_link
Add an identity provider link to a user.
add_idp_link(beta_user_service_add_idp_link_request, opts = {})
beta_user_service_add_idp_link_request
BetaUserServiceAddIDPLinkRequest
required
Request containing user ID, IDP ID, and external user information.
BetaUserServiceAddIDPLinkResponse
add_otp_email
Add OTP Email as a second factor for a user.
add_otp_email(beta_user_service_add_otp_email_request, opts = {})
beta_user_service_add_otp_email_request
BetaUserServiceAddOTPEmailRequest
required
Request containing user ID.
BetaUserServiceAddOTPEmailResponse
Example:
request = Zitadel::Client::BetaUserServiceAddOTPEmailRequest.new(
user_id: 'user_123456'
)
response = user_service.add_otp_email(request)
puts "OTP Email added successfully"
add_otpsms
Add OTP SMS as a second factor for a user.
add_otpsms(beta_user_service_add_otpsms_request, opts = {})
beta_user_service_add_otpsms_request
BetaUserServiceAddOTPSMSRequest
required
Request containing user ID.
BetaUserServiceAddOTPSMSResponse
create_passkey_registration_link
Create a passkey registration link for a user.
create_passkey_registration_link(beta_user_service_create_passkey_registration_link_request, opts = {})
beta_user_service_create_passkey_registration_link_request
BetaUserServiceCreatePasskeyRegistrationLinkRequest
required
Request containing user ID and optional return code settings.
BetaUserServiceCreatePasskeyRegistrationLinkResponse
deactivate_user
Deactivate a user account.
deactivate_user(beta_user_service_deactivate_user_request, opts = {})
beta_user_service_deactivate_user_request
BetaUserServiceDeactivateUserRequest
required
Request containing user ID to deactivate.
BetaUserServiceDeactivateUserResponse
Example:
request = Zitadel::Client::BetaUserServiceDeactivateUserRequest.new(
user_id: 'user_123456'
)
response = user_service.deactivate_user(request)
puts "User deactivated at: #{response.details.change_date}"
delete_user
Permanently delete a user account.
delete_user(beta_user_service_delete_user_request, opts = {})
beta_user_service_delete_user_request
BetaUserServiceDeleteUserRequest
required
Request containing user ID to delete.
BetaUserServiceDeleteUserResponse
get_user_by_id
Retrieve a user by their ID.
get_user_by_id(beta_user_service_get_user_by_id_request, opts = {})
beta_user_service_get_user_by_id_request
BetaUserServiceGetUserByIDRequest
required
Request containing user ID.
BetaUserServiceGetUserByIDResponse
Example:
request = Zitadel::Client::BetaUserServiceGetUserByIDRequest.new(
user_id: 'user_123456'
)
response = user_service.get_user_by_id(request)
user = response.user
puts "Username: #{user.username}"
puts "Email: #{user.human.email.email}"
list_authentication_method_types
List all authentication methods available for a user.
list_authentication_method_types(beta_user_service_list_authentication_method_types_request, opts = {})
beta_user_service_list_authentication_method_types_request
BetaUserServiceListAuthenticationMethodTypesRequest
required
Request containing user ID.
BetaUserServiceListAuthenticationMethodTypesResponse
list_users
Search and list users with filtering and pagination.
list_users(beta_user_service_list_users_request, opts = {})
beta_user_service_list_users_request
BetaUserServiceListUsersRequest
required
Request with optional query filters, pagination, and sorting.
BetaUserServiceListUsersResponse
Example:
request = Zitadel::Client::BetaUserServiceListUsersRequest.new(
query: {
limit: 50,
offset: 0
},
queries: [
{
email_query: {
email_address: 'example.com',
method: 'TEXT_QUERY_METHOD_CONTAINS'
}
}
]
)
response = user_service.list_users(request)
response.result.each do |user|
puts "User: #{user.username}"
end
lock_user
Temporarily lock a user account.
lock_user(beta_user_service_lock_user_request, opts = {})
beta_user_service_lock_user_request
BetaUserServiceLockUserRequest
required
Request containing user ID to lock.
BetaUserServiceLockUserResponse
password_reset
Request a password reset code for a user.
password_reset(beta_user_service_password_reset_request, opts = {})
beta_user_service_password_reset_request
BetaUserServicePasswordResetRequest
required
Request containing user ID and optional notification settings.
BetaUserServicePasswordResetResponse
reactivate_user
Reactivate a deactivated user account.
reactivate_user(beta_user_service_reactivate_user_request, opts = {})
beta_user_service_reactivate_user_request
BetaUserServiceReactivateUserRequest
required
Request containing user ID to reactivate.
BetaUserServiceReactivateUserResponse
register_passkey
Start passkey registration for a user.
register_passkey(beta_user_service_register_passkey_request, opts = {})
beta_user_service_register_passkey_request
BetaUserServiceRegisterPasskeyRequest
required
Request containing user ID and passkey registration details.
BetaUserServiceRegisterPasskeyResponse
register_totp
Start TOTP (Time-based One-Time Password) registration.
register_totp(beta_user_service_register_totp_request, opts = {})
beta_user_service_register_totp_request
BetaUserServiceRegisterTOTPRequest
required
Request containing user ID.
BetaUserServiceRegisterTOTPResponse
Example:
request = Zitadel::Client::BetaUserServiceRegisterTOTPRequest.new(
user_id: 'user_123456'
)
response = user_service.register_totp(request)
puts "TOTP Secret: #{response.secret}"
puts "QR Code URI: #{response.uri}"
register_u2f
Start U2F token registration for a user.
register_u2_f(beta_user_service_register_u2_f_request, opts = {})
beta_user_service_register_u2_f_request
BetaUserServiceRegisterU2FRequest
required
Request containing user ID.
BetaUserServiceRegisterU2FResponse
remove_otp_email
Remove OTP Email from a user.
remove_otp_email(beta_user_service_remove_otp_email_request, opts = {})
beta_user_service_remove_otp_email_request
BetaUserServiceRemoveOTPEmailRequest
required
Request containing user ID.
BetaUserServiceRemoveOTPEmailResponse
remove_otpsms
Remove OTP SMS from a user.
remove_otpsms(beta_user_service_remove_otpsms_request, opts = {})
beta_user_service_remove_otpsms_request
BetaUserServiceRemoveOTPSMSRequest
required
Request containing user ID.
BetaUserServiceRemoveOTPSMSResponse
remove_phone
Remove the phone number from a user.
remove_phone(beta_user_service_remove_phone_request, opts = {})
beta_user_service_remove_phone_request
BetaUserServiceRemovePhoneRequest
required
Request containing user ID.
BetaUserServiceRemovePhoneResponse
Authentication
All methods require authentication with a valid access token:
Zitadel::Client::Api.configure do |config|
config.access_token = 'YOUR_ACCESS_TOKEN'
end
Error Handling
begin
response = user_service.add_human_user(request)
rescue Zitadel::Client::ApiError => e
puts "Error #{e.code}: #{e.message}"
puts "Response: #{e.response_body}"
end
Migration Guide
Migrate to the stable User Service V2 API:
# Beta (deprecated)
beta_service = Zitadel::Client::Api::BetaUserServiceApi.new
response = beta_service.add_human_user(request)
# Stable V2 (recommended)
user_service = Zitadel::Client::Api::UserServiceApi.new
response = user_service.add_human_user(request)
