Skip to main content
The Zitadel Ruby SDK provides three authentication methods for service users. Each method is designed for different use cases and security requirements.
This SDK is designed for service user authentication only. It does not support user authentication scenarios like OAuth2, OIDC, or SAML for client applications (web, mobile, etc.).

​
Authentication Methods

The SDK supports three authentication strategies:
  1. Private Key JWT - Most secure, recommended for production
  2. Client Credentials - Simple OAuth2 flow for server-to-server
  3. Personal Access Tokens (PAT) - Quick setup for development and testing

​
Quick Comparison

MethodSecurityUse CaseToken ManagementSetup Complexity
Private Key JWTHighestProduction environmentsAutomatic refreshMedium
Client CredentialsHighTrusted server-to-serverAutomatic refreshLow
Personal Access TokenMediumDevelopment & testingManual (no refresh)Very Low

​
Private Key JWT

Best for: Production environments requiring maximum security 
require 'zitadel-client'

client = Zitadel::Client::Zitadel.with_private_key(
  "https://api.zitadel.example.com",
  "path/to/service-account.json"
)

​
Key Features

  • No client secret to manage
  • JWT signed with your private key
  • Automatic token acquisition and refresh
  • Full control over token lifetime and scopes
  • Supports key rotation

​
When to Use

  • Production deployments
  • Applications requiring highest security
  • Environments where secret rotation is complex
  • Services requiring custom token configurations
Learn more about Private Key JWT →

​
Client Credentials

Best for: Server-to-server communication in trusted environments 
require 'zitadel-client'

client = Zitadel::Client::Zitadel.with_client_credentials(
  "https://api.zitadel.example.com",
  "client_id",
  "client_secret"
)

​
Key Features

  • Standard OAuth2 client credentials flow
  • Automatic token acquisition and refresh
  • Simple setup with ID and secret
  • Built-in thread-safe token management

​
When to Use

  • Server-to-server integrations
  • Trusted backend services
  • Environments where both client and server are controlled
  • Simpler setup requirements than Private Key JWT
Learn more about Client Credentials →

​
Personal Access Tokens

Best for: Development, testing, and quick prototypes 
require 'zitadel-client'

client = Zitadel::Client::Zitadel.with_access_token(
  "https://api.zitadel.example.com",
  "dEnT7H7UfG1yHUzMGxPDnXvALn0fJE2WgQRjxHC..."
)

​
Key Features

  • Pre-generated static token
  • No token exchange required
  • Immediate usage - no setup needed
  • Simple bearer token authentication

​
When to Use

  • Local development and testing
  • Debugging and troubleshooting
  • Quick prototypes and proof of concepts
  • Scripts and one-off tasks
PATs do not automatically refresh. When they expire, you must generate a new token manually.
Learn more about Personal Access Tokens →

​
Security Considerations

​
Production Environments

For production deployments, we strongly recommend:
  1. Use Private Key JWT for maximum security
  2. Store private keys securely (never commit to version control)
  3. Implement key rotation policies
  4. Use environment variables for configuration
  5. Enable debug logging only in non-production environments

​
Token Storage

Never commit credentials to version control:
  • Service account JSON files (Private Key JWT)
  • Client secrets (Client Credentials)
  • Personal access tokens (PAT)
Best practices:
  • Use environment variables or secret management systems
  • Restrict file permissions on credential files (e.g., chmod 600)
  • Rotate credentials regularly
  • Use different credentials for different environments

​
Network Security

All authentication methods require HTTPS connections. The SDK enforces secure communication: 
# ✅ Correct - HTTPS URL
client = Zitadel::Client::Zitadel.with_access_token(
  "https://api.zitadel.example.com",
  token
)

# ❌ Avoid - HTTP will fail in production
client = Zitadel::Client::Zitadel.with_access_token(
  "http://api.zitadel.example.com",
  token
)

​
Common Configuration

All authentication methods support optional configuration during initialization: 
client = Zitadel::Client::Zitadel.with_private_key(
  "https://api.zitadel.example.com",
  "path/to/key.json"
) do |config|
  config.debug = true  # Enable debug logging
end

​
Debug Logging

Enable debug mode to troubleshoot authentication issues: 
client = Zitadel::Client::Zitadel.with_client_credentials(
  host, client_id, client_secret
) do |config|
  config.debug = true
end
This logs:
  • HTTP request and response details
  • Token acquisition and refresh events
  • API call information
Only enable debug logging in development. It may expose sensitive information in logs.

​
Migration Between Methods

You can easily switch authentication methods by changing the initialization: 
# Development - using PAT
if ENV['RAILS_ENV'] == 'development'
  client = Zitadel::Client::Zitadel.with_access_token(
    ENV['ZITADEL_HOST'],
    ENV['ZITADEL_PAT']
  )
else
  # Production - using Private Key JWT
  client = Zitadel::Client::Zitadel.with_private_key(
    ENV['ZITADEL_HOST'],
    ENV['ZITADEL_KEY_FILE']
  )
end

​
Next Steps

Private Key JWT

Secure production authentication

Client Credentials

OAuth2 server-to-server

Personal Access Tokens

Quick development setup

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us