Skip to main content

​
Overview

The SettingsServiceApi provides methods for managing settings at the instance and organization level, including branding, login policies, password policies, and more.

​
Initialize the API

require 'zitadel/client'

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

settings_api = Zitadel::Client::Api::SettingsServiceApi.new(client)

​
General Settings

Get basic information of the instance like the default organization, default language and supported languages.Required permission: policy.read
response = settings_api.get_general_settings({})

puts "Default Organization: #{response.default_org_id}"
puts "Default Language: #{response.default_language}"
puts "Supported Languages: #{response.supported_languages.join(', ')}"
Get the security settings of the ZITADEL instance.Required permission: iam.policy.read
response = settings_api.get_security_settings({})

puts "Impersonation Allowed: #{response.impersonation_allowed}"
puts "Iframe Embedding Allowed: #{response.iframe_embedding_allowed}"
Set the security settings of the instance.Required permission: iam.policy.write
request = Zitadel::Client::SettingsServiceSetSecuritySettingsRequest.new(
  impersonation_allowed: false,
  iframe_embedding_allowed: false
)

response = settings_api.set_security_settings(request)

​
Branding Settings

Get the current active branding settings for the requested context (instance or organization).Required permission: policy.read
request = Zitadel::Client::SettingsServiceGetBrandingSettingsRequest.new(
  organization_id: 'org_123' # Optional, defaults to instance
)

response = settings_api.get_branding_settings(request)

puts "Primary Color: #{response.primary_color}"
puts "Logo URL: #{response.logo_url}"
puts "Font URL: #{response.font_url}"

​
Domain Settings

Get the domain settings for the requested context (instance or organization).Required permission: policy.read
request = Zitadel::Client::SettingsServiceGetDomainSettingsRequest.new(
  organization_id: 'org_123'
)

response = settings_api.get_domain_settings(request)

puts "Login Name Check Lifetime: #{response.login_name_check_lifetime}"

​
Login Settings

Get the login settings for the requested context (instance or organization).Required permission: policy.read
request = Zitadel::Client::SettingsServiceGetLoginSettingsRequest.new(
  organization_id: 'org_123'
)

response = settings_api.get_login_settings(request)

puts "Allow Username Password: #{response.allow_username_password}"
puts "Allow Register: #{response.allow_register}"
puts "Allow External IDP: #{response.allow_external_idp}"
puts "Force MFA: #{response.force_mfa}"
puts "Passwordless Type: #{response.passwordless_type}"

​
Password Settings

Get the password complexity settings for the requested context.Required permission: policy.read
request = Zitadel::Client::SettingsServiceGetPasswordComplexitySettingsRequest.new(
  organization_id: 'org_123'
)

response = settings_api.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}"
Get the password expiry settings for the requested context.Required permission: policy.read
request = Zitadel::Client::SettingsServiceGetPasswordExpirySettingsRequest.new(
  organization_id: 'org_123'
)

response = settings_api.get_password_expiry_settings(request)

puts "Max Age Days: #{response.max_age_days}"
puts "Expire Warn Days: #{response.expire_warn_days}"

​
Lockout Settings

Get the lockout settings defining how many failed attempts are allowed before a user is locked out.Required permission: policy.read
request = Zitadel::Client::SettingsServiceGetLockoutSettingsRequest.new(
  organization_id: 'org_123'
)

response = settings_api.get_lockout_settings(request)

puts "Max Password Attempts: #{response.max_password_attempts}"
puts "Max OTP Attempts: #{response.max_otp_attempts}"

​
Identity Provider Settings

Get the current active identity providers for the requested context. Can filter by allowed actions.Required permission: policy.read
request = Zitadel::Client::SettingsServiceGetActiveIdentityProvidersRequest.new(
  organization_id: 'org_123',
  action_filters: [
    'IDP_ACTION_CREATION_ALLOWED',
    'IDP_ACTION_LINKING_ALLOWED'
  ]
)

response = settings_api.get_active_identity_providers(request)

response.identity_providers.each do |idp|
  puts "IDP: #{idp.name}, Type: #{idp.type}"
end

​
Hosted Login Translation

Returns the translations in the requested locale for the hosted login.Required permission: iam.policy.read
request = Zitadel::Client::SettingsServiceGetHostedLoginTranslationRequest.new(
  locale: 'en',
  level: 'TRANSLATION_LEVEL_ORGANIZATION',
  organization_id: 'org_123',
  ignore_inheritance: false
)

response = settings_api.get_hosted_login_translation(request)

puts "Translations: #{response.translations}"
puts "ETag: #{response.etag}"
Sets the input translations at the specified level for the input language.Required permission: iam.policy.write
request = Zitadel::Client::SettingsServiceSetHostedLoginTranslationRequest.new(
  locale: 'en',
  level: 'TRANSLATION_LEVEL_ORGANIZATION',
  organization_id: 'org_123',
  translations: {
    'login.title' => 'Welcome to Acme Corp',
    'login.description' => 'Sign in to continue'
  }
)

response = settings_api.set_hosted_login_translation(request)

​
Example: Configure Organization Settings

# Get current login settings
login_request = Zitadel::Client::SettingsServiceGetLoginSettingsRequest.new(
  organization_id: 'org_123'
)

login_settings = settings_api.get_login_settings(login_request)
puts "Current MFA Policy: #{login_settings.force_mfa}"

# Get password complexity
password_request = Zitadel::Client::SettingsServiceGetPasswordComplexitySettingsRequest.new(
  organization_id: 'org_123'
)

password_settings = settings_api.get_password_complexity_settings(password_request)
puts "Min Password Length: #{password_settings.min_length}"

# Get branding
branding_request = Zitadel::Client::SettingsServiceGetBrandingSettingsRequest.new(
  organization_id: 'org_123'
)

branding = settings_api.get_branding_settings(branding_request)
puts "Primary Color: #{branding.primary_color}"

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us