Skip to main content
Deprecated: Please move to the corresponding endpoints under Settings Service v2. This service will be removed in the next major version of ZITADEL.

​
Overview

The BetaSettingsServiceApi provides methods for retrieving and managing instance-level settings including branding, security, login policies, and more.

​
Initialization

require 'zitadel/client'

client = Zitadel::Client::ApiClient.new
client.config.access_token = 'your_access_token'

settings_service = Zitadel::Client::Api::BetaSettingsServiceApi.new(client)

​
Key Methods

​
General Settings

Retrieves general instance information including supported languages and default settings.
request = {}

response = settings_service.get_general_settings(request)

puts "Default language: #{response.default_language}"
puts "Supported languages: #{response.supported_languages.join(', ')}"
puts "Default organization ID: #{response.default_org_id}"
Returns: BetaSettingsServiceGetGeneralSettingsResponse

​
Branding Settings

Retrieves current branding settings for login pages and emails.
request = Zitadel::Client::Models::BetaSettingsServiceGetBrandingSettingsRequest.new

response = settings_service.get_branding_settings(request)

puts "Primary color: #{response.branding.primary_color}"
puts "Logo URL: #{response.branding.logo_url}"
puts "Background color: #{response.branding.background_color}"
puts "Font URL: #{response.branding.font_url}"
Returns: BetaSettingsServiceGetBrandingSettingsResponse

​
Domain Settings

Retrieves domain-related settings.
request = Zitadel::Client::Models::BetaSettingsServiceGetDomainSettingsRequest.new

response = settings_service.get_domain_settings(request)

puts "Primary domain: #{response.primary_domain}"
puts "Cookie domain: #{response.cookie_domain}"
Returns: BetaSettingsServiceGetDomainSettingsResponse

​
Login Settings

Retrieves login and authentication settings.
request = Zitadel::Client::Models::BetaSettingsServiceGetLoginSettingsRequest.new

response = settings_service.get_login_settings(request)

puts "Allow username/password: #{response.allow_username_password}"
puts "Allow external IDP: #{response.allow_external_idp}"
puts "Force MFA: #{response.force_mfa}"
puts "Passwordless type: #{response.passwordless_type}"
puts "Hide password reset: #{response.hide_password_reset_link}"
Returns: BetaSettingsServiceGetLoginSettingsResponse

​
Password Settings

Retrieves password complexity requirements.
request = Zitadel::Client::Models::BetaSettingsServiceGetPasswordComplexitySettingsRequest.new

response = settings_service.get_password_complexity_settings(request)

puts "Min length: #{response.min_length}"
puts "Has uppercase: #{response.has_uppercase}"
puts "Has lowercase: #{response.has_lowercase}"
puts "Has number: #{response.has_number}"
puts "Has symbol: #{response.has_symbol}"
Returns: BetaSettingsServiceGetPasswordComplexitySettingsResponse
Retrieves password expiration settings.
request = Zitadel::Client::Models::BetaSettingsServiceGetPasswordExpirySettingsRequest.new

response = settings_service.get_password_expiry_settings(request)

puts "Max age days: #{response.max_age_days}"
puts "Expire warn days: #{response.expire_warn_days}"
Returns: BetaSettingsServiceGetPasswordExpirySettingsResponse

​
Security Settings

Retrieves security-related settings.
request = {}

response = settings_service.get_security_settings(request)

puts "Embedded iframe enabled: #{response.embedded_iframe.enabled}"
puts "Allowed origins: #{response.embedded_iframe.origins.join(', ')}"
puts "Enable impersonation: #{response.enable_impersonation}"
Returns: BetaSettingsServiceGetSecuritySettingsResponse
Updates security settings.
request = Zitadel::Client::Models::BetaSettingsServiceSetSecuritySettingsRequest.new(
  embedded_iframe: {
    enabled: true,
    origins: ['https://myapp.com', 'https://app.example.com']
  },
  enable_impersonation: false
)

settings_service.set_security_settings(request)
Returns: BetaSettingsServiceSetSecuritySettingsResponse

​
Lockout Settings

Retrieves account lockout settings after failed login attempts.
request = Zitadel::Client::Models::BetaSettingsServiceGetLockoutSettingsRequest.new

response = settings_service.get_lockout_settings(request)

puts "Max password attempts: #{response.max_password_attempts}"
puts "Show lockout failure: #{response.show_lockout_failure}"
Returns: BetaSettingsServiceGetLockoutSettingsResponse

​
Identity Provider Settings

Retrieves list of active identity providers.
request = Zitadel::Client::Models::BetaSettingsServiceGetActiveIdentityProvidersRequest.new

response = settings_service.get_active_identity_providers(request)

response.identity_providers.each do |idp|
  puts "IDP: #{idp.name} (#{idp.type})"
  puts "  ID: #{idp.id}"
  puts "  Styling: #{idp.styling_type}"
end
Returns: BetaSettingsServiceGetActiveIdentityProvidersResponse

​
Use Cases

​
Check Password Requirements

def validate_password(password)
  settings = settings_service.get_password_complexity_settings(
    Zitadel::Client::Models::BetaSettingsServiceGetPasswordComplexitySettingsRequest.new
  )
  
  errors = []
  errors << "Too short" if password.length < settings.min_length
  errors << "Missing uppercase" if settings.has_uppercase && password !~ /[A-Z]/
  errors << "Missing lowercase" if settings.has_lowercase && password !~ /[a-z]/
  errors << "Missing number" if settings.has_number && password !~ /[0-9]/
  errors << "Missing symbol" if settings.has_symbol && password !~ /[^A-Za-z0-9]/
  
  errors
end

​
Display Login Options

def available_login_methods
  login_settings = settings_service.get_login_settings(
    Zitadel::Client::Models::BetaSettingsServiceGetLoginSettingsRequest.new
  )
  
  methods = []
  methods << :password if login_settings.allow_username_password
  methods << :passwordless if login_settings.passwordless_type != 'NOT_ALLOWED'
  
  if login_settings.allow_external_idp
    idps = settings_service.get_active_identity_providers(
      Zitadel::Client::Models::BetaSettingsServiceGetActiveIdentityProvidersRequest.new
    )
    methods << :external_idp if idps.identity_providers.any?
  end
  
  methods
end

​
Apply Branding

def apply_branding
  branding = settings_service.get_branding_settings(
    Zitadel::Client::Models::BetaSettingsServiceGetBrandingSettingsRequest.new
  )
  
  @primary_color = branding.branding.primary_color
  @background_color = branding.branding.background_color
  @logo_url = branding.branding.logo_url
  @font_url = branding.branding.font_url
  
  # Apply to views
end

​
Check Security Settings for Embedding

def can_embed_from?(origin)
  security = settings_service.get_security_settings({})
  
  if security.embedded_iframe.enabled
    security.embedded_iframe.origins.include?(origin) ||
    security.embedded_iframe.origins.include?('*')
  else
    false
  end
end

​
Settings Hierarchy

Settings are applied at different levels:
  1. System Level: Default instance settings
  2. Organization Level: Override for specific organizations
  3. Application Level: Some settings per application
The Beta Settings Service primarily returns instance-level settings.

​
Required Permissions

Most settings endpoints require:
  • iam.read - Read settings
  • iam.write - Modify settings (for set_security_settings)

​
Migration Guide

To migrate to Settings Service v2:
  1. Replace BetaSettingsServiceApi with SettingsServiceV2Api
  2. Update request/response model references
  3. Review setting structure changes
  4. Test configuration retrieval

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us