Skip to main content
The Zitadel Ruby SDK is the official Ruby client library for interacting with Zitadel’s authentication and management APIs. It provides a convenient and idiomatic way to integrate Zitadel services into your Ruby applications.
This SDK is currently in an incubating stage. While it’s production-ready, the API may evolve based on community feedback. We encourage you to try it out and share your experiences.

​
What is the Zitadel Ruby SDK?

The SDK provides a seamless wrapper around the Zitadel API, making it easy to:
  • Authenticate service users with multiple methods
  • Manage users, organizations, and projects
  • Configure applications and identity providers
  • Handle sessions and permissions
  • Access OIDC and SAML services
  • Execute administrative operations

​
Key Features

​
Comprehensive API Coverage

The SDK provides access to all major Zitadel services:
  • User Management - Create, update, and manage human and machine users
  • Organization Management - Handle organizations, projects, and roles
  • Authentication Services - OIDC, SAML, and OAuth2 integration
  • Session Management - Track and manage user sessions
  • Settings & Configuration - Customize instance and organization settings
  • Authorization - Check permissions and manage access control
  • Actions & Webhooks - Automate workflows with custom actions
  • Beta APIs - Access to preview features and services

​
Multiple Authentication Methods

The SDK supports three flexible authentication strategies:

Private Key JWT

Most secure option for production environments with JWT assertion signing

Client Credentials

Simple OAuth2 flow for trusted server-to-server communication

Personal Access Token

Quick setup for development and testing scenarios

​
Type-Safe Models

All API requests and responses use typed model classes, providing:
  • IntelliSense support in compatible IDEs
  • Clear documentation of required and optional fields
  • Reduced runtime errors through proper validation

​
Automatic Token Management

For OAuth-based authentication methods (Private Key JWT and Client Credentials), the SDK automatically:
  • Acquires access tokens on first request
  • Refreshes tokens before expiration
  • Handles token lifecycle transparently

​
Built-in Error Handling

The SDK provides structured error handling with Zitadel::Client::ApiError and Zitadel::Client::ZitadelError exceptions that include:
  • HTTP status codes
  • Error messages from the API
  • Request context for debugging

​
Architecture Overview

The SDK follows a modular architecture: 
Zitadel::Client::Zitadel (Main entry point)
  ├── Configuration (Debug, timeouts, SSL settings)
  ├── Authenticator (Handles authentication strategy)
  ├── ApiClient (HTTP client with automatic auth)
  └── Service APIs (Specialized endpoints)
      ├── users (UserServiceApi)
      ├── organizations (OrganizationServiceApi)
      ├── projects (ProjectServiceApi)
      ├── sessions (SessionServiceApi)
      ├── settings (SettingsServiceApi)
      ├── oidc (OIDCServiceApi)
      └── ... (many more services)

​
Service APIs

Each service API provides methods for specific operations. For example:
  • client.users - User management operations
  • client.organizations - Organization operations
  • client.projects - Project and application management
  • client.sessions - Session handling
  • client.settings - Instance and organization settings

​
When to Use Each Authentication Method

Use when:
  • Deploying to production environments
  • Maximum security is required
  • You need fine-grained control over token expiration
  • You want to avoid storing client secrets
How it works:
  • You create a service account in Zitadel and download a JSON key file
  • The SDK signs JWT assertions with your private key
  • Tokens are exchanged without transmitting secrets

​
Client Credentials

Use when:
  • Implementing server-to-server communication
  • Both systems are in trusted environments
  • You prefer OAuth2 standard flows
  • Simple setup is a priority
How it works:
  • You provide a client ID and client secret
  • The SDK exchanges credentials for access tokens
  • Tokens are automatically refreshed

​
Personal Access Token

Use when:
  • Developing and testing locally
  • Running one-off scripts or migrations
  • Quick prototyping is needed
  • You have a pre-generated token
How it works:
  • You generate a PAT in the Zitadel console
  • The token is passed directly in API requests
  • No dynamic token generation occurs
Personal Access Tokens should not be used in production applications as they don’t rotate automatically and may have longer lifetimes.

​
Important Limitations

This SDK is designed for service users and backend integrations. It is not suitable for:
  • Implementing user login flows in web applications
  • OAuth2/OIDC authentication for end users
  • SAML-based user authentication
  • Mobile app user authentication
  • Single Page Application (SPA) authentication
For these scenarios, use platform-specific authentication libraries or frameworks.

​
Requirements

  • Ruby 3.0 or higher
  • A Zitadel account (sign up at zitadel.com)
  • Valid API credentials (service account or personal access token)

​
Next Steps

Installation

Install the SDK and verify your setup

Quickstart

Build your first integration in minutes

​
Version Compatibility

The SDK’s major version is synchronized with the Zitadel core project’s major version to ensure compatibility. The current version is 4.1.0.beta.11, compatible with Zitadel v4.x. For detailed versioning information, see the Versioning Guide.

​
Getting Help

Build docs developers (and LLMs) love

Get started for freeTalk to us