Overview
The Zitadel class is the main entry point for interacting with the Zitadel API. It initializes the SDK with an authentication strategy and provides access to all service APIs.
Class Methods
with_access_token
Initialize the SDK with a Personal Access Token (PAT).
Zitadel::Client::Zitadel.with_access_token(host, access_token)
API URL (e.g., "https://api.zitadel.example.com")
Personal Access Token for Bearer authentication
Zitadel - SDK client configured with PAT authentication
Example:
client = Zitadel::Client::Zitadel.with_access_token(
"https://api.zitadel.cloud",
"dEnGhIWRlc3RfYWNjZXNzX3Rva2VuXzEyMzQ1"
)
with_client_credentials
Initialize the SDK using OAuth2 Client Credentials flow.
Zitadel::Client::Zitadel.with_client_credentials(host, client_id, client_secret)
Zitadel - SDK client with automatic token acquisition and refresh
Example:
client = Zitadel::Client::Zitadel.with_client_credentials(
"https://api.zitadel.cloud",
"123456789@myproject",
"client_secret_value"
)
with_private_key
Initialize the SDK via Private Key JWT assertion.
Zitadel::Client::Zitadel.with_private_key(host, key_file)
Path to service account JSON or PEM key file
Zitadel - SDK client using JWT assertion for secure, secret-less authentication
Example:
client = Zitadel::Client::Zitadel.with_private_key(
"https://api.zitadel.cloud",
"/path/to/service-account.json"
)
Constructor
initialize
Initialize the Zitadel SDK with a custom authenticator.
Zitadel::Client::Zitadel.new(authenticator) do |config|
# Optional configuration block
end
The authentication strategy to use (e.g., PersonalAccessTokenAuthenticator, ClientCredentialsAuthenticator, WebTokenAuthenticator)
Configuration - Allows customizing SDK configuration
Returns: Zitadel - Initialized SDK client
Example:
authenticator = Zitadel::Client::Auth::PersonalAccessTokenAuthenticator.new(
"https://api.zitadel.cloud",
"your_pat_token"
)
client = Zitadel::Client::Zitadel.new(authenticator) do |config|
config.timeout = 30
config.debugging = true
end
Service Accessors
The Zitadel client provides access to all Zitadel API services through instance attributes.
Stable Services
API for managing actions and flows
API for managing applications
API for managing authorizations
API for managing instance and organization features
idps
IdentityProviderServiceApi
API for managing identity providers
API for managing instances
internal_permissions
InternalPermissionServiceApi
API for managing internal permissions
API for managing organizations
API for managing projects
API for managing sessions
API for managing settings
API for managing web keys
Beta Services
Beta services are experimental and may change without notice. Use with caution in production environments.
Beta API for applications
beta_authorizations
BetaAuthorizationServiceApi
Beta API for authorizations
Beta API for instance management
Beta API for OIDC operations
beta_organizations
BetaOrganizationServiceApi
Beta API for organizations
beta_permissions
BetaInternalPermissionServiceApi
Beta API for internal permissions
Usage Examples
Basic Client Initialization
# Using Personal Access Token
client = Zitadel::Client::Zitadel.with_access_token(
"https://api.zitadel.cloud",
"your_pat_token"
)
# Access services
users = client.users.list_users
organizations = client.organizations.list_organizations
With Custom Configuration
client = Zitadel::Client::Zitadel.with_client_credentials(
"https://api.zitadel.cloud",
"client_id",
"client_secret"
) do |config|
config.timeout = 30
config.debugging = true
config.logger = Logger.new(STDOUT)
end
# Make API calls
projects = client.projects.list_projects
Using Private Key Authentication
client = Zitadel::Client::Zitadel.with_private_key(
"https://api.zitadel.cloud",
"./config/zitadel-key.json"
)
# Access beta services
telemetry = client.beta_telemetry.get_telemetry_config
Accessing Multiple Services
client = Zitadel::Client::Zitadel.with_access_token(
ENV['ZITADEL_API_URL'],
ENV['ZITADEL_PAT']
)
# Create a new user
user = client.users.create_user(user_data)
# Add user to organization
client.organizations.add_org_member(
organization_id: org_id,
user_id: user.id
)
# Assign project roles
client.projects.add_project_member(
project_id: project_id,
user_id: user.id,
roles: ['PROJECT_OWNER']
)
