Skip to main content

​
Overview

The Configuration class defines all client-level options for the Zitadel SDK, including timeouts, logging, SSL behavior, and validation controls. It allows you to customize how API calls are made and handled internally.

​
Constructor

​
initialize

Create a new Configuration instance with optional block-style configuration. 
Zitadel::Client::Configuration.new(authenticator = NoAuthAuthenticator.new) do |config|
  # Configuration block (optional)
end
​
authenticator
Authenticator
default:"NoAuthAuthenticator.new"
The authentication strategy used to authorize requests. Typically an instance implementing #authenticate(request).
Yields: Configuration - The configuration instance for customization Returns: Configuration - Initialized configuration object Example: 
config = Zitadel::Client::Configuration.new do |c|
  c.debugging = true
  c.timeout = 10
  c.verify_ssl = true
end

​
Instance Methods

​
configure

Allows modifying the current configuration instance using a block. 
configuration.configure do |config|
  # Modify configuration
end
Yields: Configuration - The configuration instance for modification Example: 
config = Zitadel::Client::Configuration.new

config.configure do |c|
  c.timeout = 60
  c.debugging = true
end

​
Configuration Options

​
Authentication

​
authenticator
Authenticator
The authentication strategy used to authorize requests. This is typically an instance of a class implementing an interface like #authenticate(request), such as NoAuthAuthenticator or a custom implementation.Note: This is read-only and set during initialization.

​
Debugging and Logging

​
debugging
Boolean
default:"false"
Enables or disables debug logging. When enabled, HTTP request and response details are logged via the configured logger instance.
​
logger
#debug
default:"Rails.logger or STDOUT"
The logger used to output debugging information. Defaults to Rails.logger if Rails is defined; otherwise, logs to STDOUT.
Example: 
config.debugging = true
config.logger = Logger.new('zitadel.log')

​
Timeouts

​
timeout
Integer
default:"0"
Request timeout duration in seconds. If set to 0, requests will never time out.
Example: 
# Set 30 second timeout
config.timeout = 30

# Disable timeout (wait indefinitely)
config.timeout = 0

​
SSL/TLS Configuration

​
verify_ssl
Boolean
default:"true"
Controls whether SSL certificates are verified when making HTTPS requests. Set to false to bypass certificate verification.Warning: This should always be true in production environments.
​
verify_ssl_host
Boolean
default:"true"
Controls whether SSL hostnames are verified during HTTPS communication. Set to false to skip hostname verification.Warning: Disabling this weakens transport security.
​
ssl_ca_cert
String
default:"nil"
Path to the certificate file used to verify the peer. This is used in place of system-level certificate stores.
​
cert_file
String
default:"nil"
Path to the client certificate file for mutual TLS (mTLS). This is optional and only required when the server expects client-side certificates.
​
key_file
String
default:"nil"
Path to the private key file for the client certificate. Used with cert_file during mutual TLS authentication.
Example: 
# Standard SSL verification
config.verify_ssl = true
config.verify_ssl_host = true

# Custom CA certificate
config.ssl_ca_cert = '/path/to/ca-bundle.crt'

# Mutual TLS (mTLS)
config.cert_file = '/path/to/client.crt'
config.key_file = '/path/to/client.key'

​
Validation

​
client_side_validation
Boolean
default:"true"
Enables or disables client-side request validation. When disabled, validation of input parameters is skipped.
Example: 
# Enable validation (recommended)
config.client_side_validation = true

# Disable validation (use with caution)
config.client_side_validation = false

​
HTTP Configuration

​
user_agent
String
default:"zitadel-client/{VERSION} (...)"
The User-Agent header to be sent with HTTP requests. Set this to identify your client or library when making requests.Default format: zitadel-client/{VERSION} (lang=ruby; lang_version={RUBY_VERSION}; os={RUBY_PLATFORM}; arch={host_cpu})
​
params_encoding
Symbol | nil
default:"nil"
Custom encoding strategy for query parameters that are arrays. Set this if your server expects a specific collection format (e.g., multi, csv, etc.).
Example: 
# Custom User-Agent
config.user_agent = 'MyApp/1.0 (Zitadel Integration)'

# Custom params encoding
config.params_encoding = :multi

​
File Operations

​
temp_folder_path
String
default:"nil"
Directory path used to temporarily store files returned by API responses (e.g., when downloading files).
Example: 
config.temp_folder_path = '/tmp/zitadel-downloads'

​
Complete Configuration Example

authenticator = Zitadel::Client::Auth::PersonalAccessTokenAuthenticator.new(
  "https://api.zitadel.cloud",
  "your_token"
)

config = Zitadel::Client::Configuration.new(authenticator) do |c|
  # Debugging
  c.debugging = true
  c.logger = Logger.new(STDOUT)
  
  # Timeouts
  c.timeout = 30
  
  # SSL/TLS
  c.verify_ssl = true
  c.verify_ssl_host = true
  c.ssl_ca_cert = '/etc/ssl/certs/ca-bundle.crt'
  
  # Validation
  c.client_side_validation = true
  
  # HTTP
  c.user_agent = 'MyApp/2.0 (Custom Integration)'
  
  # File operations
  c.temp_folder_path = '/tmp/zitadel'
end

​
Usage with Client

Configuration is typically done through the client initialization methods:

​
With Access Token

client = Zitadel::Client::Zitadel.with_access_token(
  "https://api.zitadel.cloud",
  "your_token"
) do |config|
  config.timeout = 30
  config.debugging = true
end

​
With Client Credentials

client = Zitadel::Client::Zitadel.with_client_credentials(
  "https://api.zitadel.cloud",
  "client_id",
  "client_secret"
) do |config|
  config.verify_ssl = true
  config.logger = Rails.logger
end

​
With Private Key

client = Zitadel::Client::Zitadel.with_private_key(
  "https://api.zitadel.cloud",
  "./service-account.json"
) do |config|
  config.timeout = 60
  config.client_side_validation = false
end

​
Environment-Specific Configuration

# Development
if Rails.env.development?
  config.debugging = true
  config.verify_ssl = false  # For local testing only
  config.logger = Logger.new(STDOUT)
end

# Production
if Rails.env.production?
  config.debugging = false
  config.verify_ssl = true
  config.verify_ssl_host = true
  config.timeout = 30
  config.logger = Rails.logger
end

# Test
if Rails.env.test?
  config.client_side_validation = false
  config.timeout = 5
end

​
Security Best Practices

Always follow these security guidelines when configuring the SDK:
  1. SSL Verification: Always keep verify_ssl and verify_ssl_host set to true in production
  2. Timeouts: Set reasonable timeout values to prevent hanging requests
  3. Logging: Be careful not to log sensitive information when debugging is enabled
  4. Client-Side Validation: Keep validation enabled unless you have a specific reason to disable it
  5. User Agent: Use a descriptive user agent to help identify your application in logs
# Production-safe configuration
config = Zitadel::Client::Configuration.new(authenticator) do |c|
  c.verify_ssl = true
  c.verify_ssl_host = true
  c.timeout = 30
  c.client_side_validation = true
  c.debugging = false  # Disable in production
end

Build docs developers (and LLMs) love

Get started for freeTalk to us