Skip to main content
Deprecated: Feature Service v2 will replace this API. This service will be removed in the next major version of ZITADEL.

​
Overview

The BetaFeatureServiceApi provides methods for managing feature flags at different levels: system, instance, organization, and user.

​
Initialization

require 'zitadel/client'

client = Zitadel::Client::ApiClient.new
client.config.access_token = 'your_access_token'

feature_service = Zitadel::Client::Api::BetaFeatureServiceApi.new(client)

​
Feature Hierarchy

Features cascade from system level down:
  1. System Level - Default features (requires system permissions)
  2. Instance Level - Override for entire instance
  3. Organization Level - Override for specific organization
  4. User Level - Override for individual users

​
Key Methods

​
System Features

Retrieves default feature flags at the system level.
request = {}

response = feature_service.get_system_features(request)

puts "Login default redirect: #{response.login_default_redirect.enabled}"
puts "Actions: #{response.actions.enabled}"
puts "Improved performance: #{response.improved_performance.enabled}"
Returns: BetaFeatureServiceGetSystemFeaturesResponse
Updates system-level feature flags (system admin only).
request = Zitadel::Client::Models::BetaFeatureServiceSetSystemFeaturesRequest.new(
  login_default_redirect: { enabled: true },
  actions: { enabled: true },
  improved_performance: { enabled: true }
)

feature_service.set_system_features(request)
Returns: BetaFeatureServiceSetSystemFeaturesResponse
Resets system features to platform defaults.
request = {}

feature_service.reset_system_features(request)
Returns: BetaFeatureServiceResetSystemFeaturesResponse

​
Instance Features

Retrieves feature flags for the current instance.
request = Zitadel::Client::Models::BetaFeatureServiceGetInstanceFeaturesRequest.new(
  inheritance: true # Include inherited system features
)

response = feature_service.get_instance_features(request)

puts "Login default redirect: #{response.login_default_redirect.enabled}"
puts "Trigger introspection: #{response.trigger_introspection_projections.enabled}"
Returns: BetaFeatureServiceGetInstanceFeaturesResponse
Configures features for the entire instance.
request = Zitadel::Client::Models::BetaFeatureServiceSetInstanceFeaturesRequest.new(
  login_default_redirect: { enabled: true },
  trigger_introspection_projections: { enabled: true },
  legacy_introspection: { enabled: false }
)

feature_service.set_instance_features(request)
Returns: BetaFeatureServiceSetInstanceFeaturesResponse
Resets instance features to system defaults.
request = {}

feature_service.reset_instance_features(request)
Returns: BetaFeatureServiceResetInstanceFeaturesResponse

​
Organization Features

Retrieves features for a specific organization.
request = Zitadel::Client::Models::BetaFeatureServiceGetOrganizationFeaturesRequest.new(
  organization_id: '123456789',
  inheritance: true
)

response = feature_service.get_organization_features(request)

puts "Actions: #{response.actions.enabled}"
puts "Trigger actions: #{response.trigger_actions.enabled}"
Returns: BetaFeatureServiceGetOrganizationFeaturesResponse
Configures features for a specific organization.
request = Zitadel::Client::Models::BetaFeatureServiceSetOrganizationFeaturesRequest.new(
  organization_id: '123456789',
  actions: { enabled: true },
  trigger_actions: { enabled: true }
)

feature_service.set_organization_features(request)
Returns: BetaFeatureServiceSetOrganizationFeaturesResponse
Resets organization features to instance defaults.
request = Zitadel::Client::Models::BetaFeatureServiceResetOrganizationFeaturesRequest.new(
  organization_id: '123456789'
)

feature_service.reset_organization_features(request)
Returns: BetaFeatureServiceResetOrganizationFeaturesResponse

​
User Features

Retrieves features for a specific user.
request = Zitadel::Client::Models::BetaFeatureServiceGetUserFeaturesRequest.new(
  user_id: '987654321',
  inheritance: true
)

response = feature_service.get_user_features(request)

puts "User schema: #{response.user_schema.enabled}"
Returns: BetaFeatureServiceGetUserFeaturesResponse
Configures features for a specific user.
request = Zitadel::Client::Models::BetaFeatureServiceSetUserFeatureRequest.new(
  user_id: '987654321',
  user_schema: { enabled: true }
)

feature_service.set_user_features(request)
Returns: BetaFeatureServiceSetUserFeaturesResponse
Resets user features to organization defaults.
request = Zitadel::Client::Models::BetaFeatureServiceResetUserFeaturesRequest.new(
  user_id: '987654321'
)

feature_service.reset_user_features(request)
Returns: BetaFeatureServiceResetUserFeaturesResponse

​
Available Features

​
Authentication & Login

  • login_default_redirect - Enable default redirect after login
  • trigger_introspection_projections - Trigger projections on introspection
  • legacy_introspection - Use legacy introspection format

​
Actions & Automation

  • actions - Enable actions (webhooks/functions)
  • trigger_actions - Enable action triggers on events

​
Performance

  • improved_performance - Enable performance optimizations

​
User Management

  • user_schema - Enable custom user schemas

​
Use Cases

​
Check if Feature is Enabled

def feature_enabled?(organization_id, feature_name)
  request = Zitadel::Client::Models::BetaFeatureServiceGetOrganizationFeaturesRequest.new(
    organization_id: organization_id,
    inheritance: true # Include inherited features
  )
  
  response = feature_service.get_organization_features(request)
  
  # Access feature by name
  feature = response.send(feature_name)
  feature&.enabled || false
rescue
  false # Default to disabled on error
end

# Usage
if feature_enabled?('123456789', 'actions')
  # Execute actions
end

​
Enable Feature for Organization

def enable_actions_for_org(organization_id)
  request = Zitadel::Client::Models::BetaFeatureServiceSetOrganizationFeaturesRequest.new(
    organization_id: organization_id,
    actions: { enabled: true },
    trigger_actions: { enabled: true }
  )
  
  feature_service.set_organization_features(request)
  puts "Actions enabled for organization #{organization_id}"
end

​
Feature Audit Report

def feature_audit_report(organization_id)
  # Get org features with inheritance
  request = Zitadel::Client::Models::BetaFeatureServiceGetOrganizationFeaturesRequest.new(
    organization_id: organization_id,
    inheritance: true
  )
  
  response = feature_service.get_organization_features(request)
  
  report = {
    organization_id: organization_id,
    features: {}
  }
  
  # Iterate through all features
  response.to_hash.each do |key, value|
    next unless value.is_a?(Hash) && value.key?(:enabled)
    
    report[:features][key] = {
      enabled: value[:enabled],
      source: value[:source] # 'SYSTEM', 'INSTANCE', 'ORGANIZATION'
    }
  end
  
  report
end

​
Rollout Feature Gradually

def gradual_feature_rollout(feature_name, percentage)
  # Get all organizations
  organizations = list_all_organizations
  
  # Calculate how many to enable
  count = (organizations.size * percentage / 100.0).ceil
  
  # Randomly select organizations
  selected_orgs = organizations.sample(count)
  
  selected_orgs.each do |org|
    request = Zitadel::Client::Models::BetaFeatureServiceSetOrganizationFeaturesRequest.new(
      organization_id: org.id
    )
    
    # Dynamically set the feature
    request.send("#{feature_name}=", { enabled: true })
    
    feature_service.set_organization_features(request)
    puts "Enabled #{feature_name} for org #{org.name}"
  end
  
  puts "Feature #{feature_name} enabled for #{count}/#{organizations.size} organizations (#{percentage}%)"
end

# Usage: Enable for 10% of organizations
gradual_feature_rollout('actions', 10)

​
Reset All Features to Defaults

def reset_all_features(organization_id)
  puts "Resetting all features for organization #{organization_id}..."
  
  request = Zitadel::Client::Models::BetaFeatureServiceResetOrganizationFeaturesRequest.new(
    organization_id: organization_id
  )
  
  feature_service.reset_organization_features(request)
  
  puts "All features reset to defaults"
end

​
Feature Inheritance

When inheritance: true is set: 
# Request with inheritance
request = Zitadel::Client::Models::BetaFeatureServiceGetOrganizationFeaturesRequest.new(
  organization_id: '123456789',
  inheritance: true
)

response = feature_service.get_organization_features(request)

# Response includes source of each feature
response.actions # { enabled: true, source: 'INSTANCE' }
response.trigger_actions # { enabled: false, source: 'ORGANIZATION' }
Feature sources:
  • SYSTEM - From system defaults
  • INSTANCE - From instance configuration
  • ORGANIZATION - Explicitly set for organization
  • USER - Explicitly set for user

​
Migration Guide

To migrate to Feature Service v2:
  1. Replace BetaFeatureServiceApi with FeatureServiceV2Api
  2. Update feature flag names (may change)
  3. Review feature hierarchy
  4. Test feature inheritance

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us