Skip to main content
This guide walks you through installing the Zitadel Ruby SDK and verifying your setup.

​
Prerequisites

Before installing the SDK, ensure you have:
  • Ruby 3.0 or higher installed on your system
  • Bundler for dependency management (recommended)
  • A Zitadel account with API credentials

​
Check Your Ruby Version

Verify your Ruby version meets the minimum requirement: 
ruby --version
You should see output like ruby 3.0.0 or higher. If you need to upgrade Ruby, visit ruby-lang.org.

​
Installation Methods

You can install the SDK using either RubyGems directly or Bundler (recommended). Add the gem to your Gemfile:
Gemfile
gem 'zitadel-client'
Then install dependencies: 
bundle install
Using Bundler ensures all dependencies are properly managed and version-locked for reproducible builds.

​
Option 2: Using RubyGems

Install the gem directly: 
gem install zitadel-client

​
Option 3: Quick Add with Bundler CLI

Add the gem and install in one command: 
bundle add zitadel-client

​
Dependencies

The SDK automatically installs the following dependencies:
  • oauth2 (~> 2.0) - OAuth2 client library for token management
  • typhoeus (~> 1.0) - Fast HTTP client built on libcurl
  • zeitwerk (~> 2.5) - Efficient code loading
  • cgi (>= 0.1) - CGI support
  • date (>= 3.0) - Date and time handling
  • logger (>= 1.4) - Logging functionality
  • net-http (>= 0.1) - HTTP client
  • tempfile (>= 0.1) - Temporary file management
  • time (>= 0.1) - Time utilities
  • uri (>= 0.10) - URI parsing
  • warning (~> 1.5.0) - Warning management
All dependencies are installed automatically - no manual configuration needed.

​
Verify Installation

After installation, verify the SDK is available:
1

Open Ruby Interactive Shell

Start an interactive Ruby session:
irb
2

Require the SDK

Load the Zitadel client library:
require 'zitadel-client'
If successful, you’ll see => true.
3

Check the Version

Verify the SDK version:
puts Zitadel::Client::VERSION
You should see the version number (e.g., 4.1.0.beta.11).
4

Test Basic Initialization

Create a test client to ensure everything works:
client = Zitadel::Client::Zitadel.with_access_token(
  "https://example.zitadel.cloud",
  "dummy-token"
)
puts "SDK initialized successfully!"
This test only verifies initialization - it won’t make actual API calls with a dummy token.

​
Project Setup

Once installed, require the SDK in your Ruby files: 
require 'zitadel-client'
For Rails applications, the gem will be automatically required if it’s in your Gemfile.

​
In a Ruby Script

script.rb
#!/usr/bin/env ruby

require 'zitadel-client'

# Your code here
client = Zitadel::Client::Zitadel.with_access_token(
  ENV['ZITADEL_URL'],
  ENV['ZITADEL_TOKEN']
)

puts "Connected to Zitadel!"

​
In a Rails Application

Create an initializer:
config/initializers/zitadel.rb
# frozen_string_literal: true

require 'zitadel-client'

# Configure client in a service or controller
# See quickstart for authentication examples

​
Troubleshooting

​
Common Installation Issues

Error: required_ruby_version requirement not satisfiedSolution: Upgrade to Ruby 3.0 or higher. Use a version manager like rbenv or asdf:
# Using rbenv
rbenv install 3.0.0
rbenv local 3.0.0

# Using asdf
asdf install ruby 3.0.0
asdf local ruby 3.0.0
Error: Failed to build gem native extension for typhoeusSolution: Install libcurl development headers:
# Ubuntu/Debian
sudo apt-get install libcurl4-openssl-dev

# macOS
brew install curl

# Fedora/RHEL
sudo dnf install libcurl-devel
Then retry the installation:
bundle install
Error: You don't have write permissionsSolution: Either use Bundler (recommended) or install with sudo:
# Recommended: Use Bundler
bundle install --path vendor/bundle

# Alternative: System-wide install (not recommended)
sudo gem install zitadel-client
Error: Connection timeout or Unable to download dataSolution: Configure gem sources and proxy settings:
# Add rubygems source explicitly
gem sources --add https://rubygems.org/

# For proxy environments
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

bundle install
Error: Bundler could not find compatible versionsSolution: Update your bundle or try:
# Update all gems
bundle update

# Or update just zitadel-client
bundle update zitadel-client

# Check for specific conflicts
bundle install --verbose

​
Verify Network Connectivity

Test that you can reach Zitadel’s API: 
curl -I https://example.zitadel.cloud
Replace example.zitadel.cloud with your actual Zitadel instance URL.

​
Enable Debug Logging

If you encounter issues, enable debug mode to see detailed HTTP logs: 
client = Zitadel::Client::Zitadel.with_access_token(
  "https://example.zitadel.cloud",
  "your-token"
) do |config|
  config.debugging = true
  config.logger = Logger.new(STDOUT)
end
This will output detailed request and response information.

​
Configuration Options

The SDK supports various configuration options: 
client = Zitadel::Client::Zitadel.with_access_token(
  "https://example.zitadel.cloud",
  "your-token"
) do |config|
  # Enable debug logging
  config.debugging = true
  
  # Set custom timeout (seconds, 0 = no timeout)
  config.timeout = 30
  
  # SSL certificate verification (always true in production)
  config.verify_ssl = true
  config.verify_ssl_host = true
  
  # Custom logger
  config.logger = Logger.new('zitadel.log')
  
  # Custom User-Agent
  config.user_agent = "MyApp/1.0 #{config.user_agent}"
end
Never disable SSL verification (verify_ssl = false) in production environments. This exposes your application to man-in-the-middle attacks.

​
Next Steps

Now that the SDK is installed, you’re ready to authenticate and make your first API call:

Quickstart Guide

Learn how to authenticate and create your first user in minutes

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us