Configuration

Overview

The Zitadel Ruby SDK provides a flexible Configuration class that allows you to customize HTTP client behavior, SSL settings, timeouts, logging, and more. Configuration is set during SDK initialization and can be modified using a configuration block.

Basic Configuration

Using Configuration Blocks

The simplest way to configure the SDK is during initialization:

require 'zitadel-client'

client = Zitadel::Client::Zitadel.with_access_token(
  "https://example.us1.zitadel.cloud",
  "your-access-token"
) do |config|
  config.timeout = 30
  config.debugging = true
  config.verify_ssl = true
end

Accessing Configuration Directly

You can also create and modify a Configuration object directly:

require 'zitadel-client'

config = Zitadel::Client::Configuration.new do |c|
  c.debugging = true
  c.timeout = 10
  c.verify_ssl = true
end

# Use with an authenticator
authenticator = Zitadel::Client::Auth::PersonalAccessTokenAuthenticator.new(
  "https://example.us1.zitadel.cloud",
  "your-token"
)

client = Zitadel::Client::Zitadel.new(authenticator) do |c|
  c.timeout = config.timeout
  c.debugging = config.debugging
end

Configuration options are defined in lib/zitadel/client/configuration.rb:21-179

Configuration Options

HTTP & Network Settings

Timeout

Controls how long the SDK waits for API responses (in seconds).

client = Zitadel::Client::Zitadel.with_private_key(
  "https://example.us1.zitadel.cloud",
  "key.json"
) do |config|
  config.timeout = 30  # 30 seconds
end

Type: Integer
Default: 0 (no timeout)
Recommendation: Set to 30-60 seconds in production

A timeout of 0 means requests will never time out, which can cause your application to hang indefinitely if the API is unresponsive.

User Agent

Customize the User-Agent header sent with requests.

client = Zitadel::Client::Zitadel.with_client_credentials(
  "https://example.us1.zitadel.cloud",
  "client-id",
  "client-secret"
) do |config|
  config.user_agent = "MyApp/1.0.0 (Ruby #{RUBY_VERSION})"
end

Type: String
Default: "zitadel-client/{VERSION} (lang=ruby; lang_version={RUBY_VERSION}; os={RUBY_PLATFORM}; arch={CPU_ARCH})"

SSL/TLS Settings

SSL Verification

Control SSL certificate and hostname verification.

client = Zitadel::Client::Zitadel.with_access_token(
  "https://example.us1.zitadel.cloud",
  "token"
) do |config|
  config.verify_ssl = true       # Verify SSL certificates
  config.verify_ssl_host = true  # Verify hostname matches certificate
end

verify_ssl: Verifies SSL peer certificates
verify_ssl_host: Verifies SSL hostname
Type: Boolean
Default: true for both

Never set verify_ssl or verify_ssl_host to false in production. This exposes your application to man-in-the-middle attacks.

Custom SSL Certificates

Provide custom CA certificates or client certificates for mutual TLS (mTLS).

client = Zitadel::Client::Zitadel.with_private_key(
  "https://example.us1.zitadel.cloud",
  "key.json"
) do |config|
  # Custom CA certificate for peer verification
  config.ssl_ca_cert = "/path/to/ca-bundle.crt"
  
  # Client certificate for mutual TLS
  config.cert_file = "/path/to/client-cert.pem"
  config.key_file = "/path/to/client-key.pem"
end

ssl_ca_cert: Path to CA certificate bundle
cert_file: Path to client certificate (for mTLS)
key_file: Path to client private key (for mTLS)
Type: String
Default: nil

Debugging & Logging

Enable Debug Mode

Enables verbose HTTP request/response logging.

client = Zitadel::Client::Zitadel.with_access_token(
  "https://example.us1.zitadel.cloud",
  "token"
) do |config|
  config.debugging = true
end

# Now API calls will log detailed information
client.users.list_users(
  Zitadel::Client::UserServiceListUsersRequest.new(limit: 5)
)

Example debug output:

HTTP request body param ~BEGIN~
{"limit":5}
~END~

HTTP response body ~BEGIN~
{"result":[{"userId":"123","userName":"john.doe"}]}
~END~

Type: Boolean
Default: false

Debug mode logs full request/response bodies which may contain sensitive data. Only enable in development or secure logging environments.

Custom Logger

Provide a custom logger instance.

require 'logger'

custom_logger = Logger.new('zitadel.log')
custom_logger.level = Logger::DEBUG

client = Zitadel::Client::Zitadel.with_private_key(
  "https://example.us1.zitadel.cloud",
  "key.json"
) do |config|
  config.debugging = true
  config.logger = custom_logger
end

Type: Any object responding to #debug
Default: Rails.logger (if Rails is defined), otherwise Logger.new(STDOUT)

Validation Settings

Client-Side Validation

Enable or disable request parameter validation before sending to the API.

client = Zitadel::Client::Zitadel.with_client_credentials(
  "https://example.us1.zitadel.cloud",
  "client-id",
  "secret"
) do |config|
  config.client_side_validation = false  # Disable validation
end

Type: Boolean
Default: true

Disabling client-side validation can improve performance but may result in API errors for invalid requests.

Advanced Settings

Temporary File Path

Directory for storing temporary files (e.g., downloaded files from API responses).

client = Zitadel::Client::Zitadel.with_access_token(
  "https://example.us1.zitadel.cloud",
  "token"
) do |config|
  config.temp_folder_path = "/tmp/zitadel-downloads"
end

Type: String
Default: System temp directory

Query Parameter Encoding

Customize how array parameters are encoded in query strings.

client = Zitadel::Client::Zitadel.with_private_key(
  "https://example.us1.zitadel.cloud",
  "key.json"
) do |config|
  config.params_encoding = :multi  # ?id=1&id=2&id=3
  # Other options: :csv, :ssv, :tsv, :pipes
end

Type: Symbol or nil
Default: nil (standard encoding)

Configuration Examples

Production Configuration

require 'zitadel-client'
require 'logger'

production_logger = Logger.new('log/zitadel.log')
production_logger.level = Logger::WARN

client = Zitadel::Client::Zitadel.with_private_key(
  ENV['ZITADEL_HOST'],
  ENV['ZITADEL_KEY_FILE']
) do |config|
  # Security
  config.verify_ssl = true
  config.verify_ssl_host = true
  
  # Performance
  config.timeout = 60
  config.client_side_validation = true
  
  # Logging
  config.debugging = false
  config.logger = production_logger
end

Development Configuration

require 'zitadel-client'

client = Zitadel::Client::Zitadel.with_access_token(
  "https://example.us1.zitadel.cloud",
  ENV['ZITADEL_DEV_TOKEN']
) do |config|
  # Enable debug logging
  config.debugging = true
  config.logger = Logger.new(STDOUT)
  
  # Longer timeout for debugging
  config.timeout = 300
  
  # Keep validation enabled
  config.client_side_validation = true
end

Rails Integration

# config/initializers/zitadel.rb
require 'zitadel-client'

ZITADEL_CLIENT = Zitadel::Client::Zitadel.with_private_key(
  Rails.application.credentials.dig(:zitadel, :host),
  Rails.root.join('config', 'zitadel-key.json').to_s
) do |config|
  config.timeout = 30
  config.logger = Rails.logger
  config.debugging = Rails.env.development?
end

Complete configuration reference

config = Zitadel::Client::Configuration.new do |c|
  # Authentication (set via authenticator parameter)
  # c.authenticator = <Authenticator instance>
  
  # HTTP Settings
  c.timeout = 60                    # seconds, 0 = no timeout
  c.user_agent = "MyApp/1.0"
  
  # SSL/TLS Settings
  c.verify_ssl = true               # verify peer certificates
  c.verify_ssl_host = true          # verify hostname
  c.ssl_ca_cert = nil               # custom CA certificate path
  c.cert_file = nil                 # client certificate (mTLS)
  c.key_file = nil                  # client private key (mTLS)
  
  # Debugging & Logging
  c.debugging = false               # enable debug logging
  c.logger = Logger.new(STDOUT)     # custom logger
  
  # Validation
  c.client_side_validation = true   # validate before API calls
  
  # Advanced
  c.temp_folder_path = "/tmp"       # temp file directory
  c.params_encoding = nil           # query param encoding
end

Environment Variables Pattern

# .env
ZITADEL_HOST=https://example.us1.zitadel.cloud
ZITADEL_KEY_FILE=/path/to/key.json
ZITADEL_TIMEOUT=30
ZITADEL_DEBUG=false

# application.rb
require 'zitadel-client'
require 'dotenv/load'

client = Zitadel::Client::Zitadel.with_private_key(
  ENV['ZITADEL_HOST'],
  ENV['ZITADEL_KEY_FILE']
) do |config|
  config.timeout = ENV.fetch('ZITADEL_TIMEOUT', 60).to_i
  config.debugging = ENV.fetch('ZITADEL_DEBUG', 'false') == 'true'
end

Next Steps

Learn about Error Handling
Enable Debugging for troubleshooting
Understand Service Users authentication

Getting Started

Authentication

Core Concepts

Guides

Overview

Basic Configuration

Using Configuration Blocks

Accessing Configuration Directly

Configuration Options

HTTP & Network Settings

Timeout

User Agent

SSL/TLS Settings

SSL Verification

Custom SSL Certificates

Debugging & Logging

Enable Debug Mode

Custom Logger

Validation Settings

Client-Side Validation

Advanced Settings

Temporary File Path

Query Parameter Encoding

Configuration Examples

Production Configuration

Development Configuration

Rails Integration

Environment Variables Pattern

Next Steps

Build docs developers (and LLMs) love

Getting Started

Authentication

Core Concepts

Guides

​Overview

​Basic Configuration

​Using Configuration Blocks

​Accessing Configuration Directly

​Configuration Options

​HTTP & Network Settings

​Timeout

​User Agent

​SSL/TLS Settings

​SSL Verification

​Custom SSL Certificates

​Debugging & Logging

​Enable Debug Mode

​Custom Logger

​Validation Settings

​Client-Side Validation

​Advanced Settings

​Temporary File Path

​Query Parameter Encoding

​Configuration Examples

​Production Configuration

​Development Configuration

​Rails Integration

​Environment Variables Pattern

​Next Steps

Build docs developers (and LLMs) love

Overview

Basic Configuration

Using Configuration Blocks

Accessing Configuration Directly

Configuration Options

HTTP & Network Settings

Timeout

User Agent

SSL/TLS Settings

SSL Verification

Custom SSL Certificates

Debugging & Logging

Enable Debug Mode

Custom Logger

Validation Settings

Client-Side Validation

Advanced Settings

Temporary File Path

Query Parameter Encoding

Configuration Examples

Production Configuration

Development Configuration

Rails Integration

Environment Variables Pattern

Next Steps