Skip to main content

​
Overview

The FeatureServiceApi provides methods for managing feature flags across different levels in Zitadel: system, instance, organization, and user. Features control platform behaviors and capabilities.

​
Initialize the API

require 'zitadel/client'

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

feature_api = Zitadel::Client::Api::FeatureServiceApi.new(client)

​
System Features

Returns all configured features for the system. Unset fields mean the feature is the current system default.Required permission: None
response = feature_api.get_system_features({})

puts "Login Default Org: #{response.login_default_org.enabled}"
puts "Trigger Introspection Projections: #{response.trigger_introspection_projections.enabled}"
Configure and set features that apply to the complete system. Only fields present in the request are set or unset.Required permission: system.feature.write
request = Zitadel::Client::FeatureServiceSetSystemFeaturesRequest.new(
  login_default_org: {
    enabled: true
  },
  trigger_introspection_projections: {
    enabled: false
  }
)

response = feature_api.set_system_features(request)
Deletes ALL configured features for the system, reverting the behaviors to system defaults.Required permission: system.feature.delete
response = feature_api.reset_system_features({})

​
Instance Features

Returns all configured features for an instance. Unset fields mean the feature is the current system default.Required permission: None
request = Zitadel::Client::FeatureServiceGetInstanceFeaturesRequest.new(
  instance_id: 'instance_123' # Optional
)

response = feature_api.get_instance_features(request)

puts "Login Default Org: #{response.login_default_org.enabled}"
puts "User Schema: #{response.user_schema.enabled}"
Configure and set features that apply to a complete instance. Only fields present in the request are set or unset.Required permission: iam.feature.write
request = Zitadel::Client::FeatureServiceSetInstanceFeaturesRequest.new(
  login_default_org: {
    enabled: true
  },
  user_schema: {
    enabled: true
  }
)

response = feature_api.set_instance_features(request)
Deletes ALL configured features for an instance, reverting the behaviors to system defaults.Required permission: iam.feature.delete
response = feature_api.reset_instance_features({})

​
Organization Features

Returns all configured features for an organization. Unset fields mean the feature is the current instance default.Required permissions:
  • org.feature.read
  • No permission required for the organization the user belongs to
request = Zitadel::Client::FeatureServiceGetOrganizationFeaturesRequest.new(
  organization_id: 'org_123'
)

response = feature_api.get_organization_features(request)

puts "Login Default Org: #{response.login_default_org.enabled}"
Configure and set features that apply to an organization. Only fields present in the request are set or unset.Required permission: org.feature.write
request = Zitadel::Client::FeatureServiceSetOrganizationFeaturesRequest.new(
  organization_id: 'org_123',
  login_default_org: {
    enabled: false
  }
)

response = feature_api.set_organization_features(request)
Deletes ALL configured features for an organization, reverting the behaviors to instance defaults.Required permission: org.feature.delete
request = Zitadel::Client::FeatureServiceResetOrganizationFeaturesRequest.new(
  organization_id: 'org_123'
)

response = feature_api.reset_organization_features(request)

​
User Features

Returns all configured features for a user. Unset fields mean the feature is the current organization default.Required permissions:
  • user.feature.read
  • No permission required for the own user
request = Zitadel::Client::FeatureServiceGetUserFeaturesRequest.new(
  user_id: 'user_123'
)

response = feature_api.get_user_features(request)
Configure and set features that apply to a user. Only fields present in the request are set or unset.Required permission: user.feature.write
request = Zitadel::Client::FeatureServiceSetUserFeatureRequest.new(
  user_id: 'user_123',
  # Add specific user features here
)

response = feature_api.set_user_features(request)
Deletes ALL configured features for a user, reverting the behaviors to organization defaults.Required permission: user.feature.delete
request = Zitadel::Client::FeatureServiceResetUserFeaturesRequest.new(
  user_id: 'user_123'
)

response = feature_api.reset_user_features(request)

​
Feature Hierarchy

Features follow an inheritance hierarchy:
  • System: Base defaults for all instances
  • Instance: Overrides system defaults
  • Organization: Overrides instance defaults
  • User: Overrides organization defaults

​
Common Features

​
Login Default Org

Controls whether users must specify an organization during login. 
login_default_org: {
  enabled: true
}

​
User Schema

Enables custom user schema functionality. 
user_schema: {
  enabled: true
}

​
Trigger Introspection Projections

Controls whether introspection triggers projection updates. 
trigger_introspection_projections: {
  enabled: false
}

​
Example: Configure Organization Features

# Get current organization features
get_request = Zitadel::Client::FeatureServiceGetOrganizationFeaturesRequest.new(
  organization_id: 'org_123'
)

current_features = feature_api.get_organization_features(get_request)
puts "Current login_default_org: #{current_features.login_default_org.enabled}"

# Update organization features
set_request = Zitadel::Client::FeatureServiceSetOrganizationFeaturesRequest.new(
  organization_id: 'org_123',
  login_default_org: {
    enabled: false
  },
  user_schema: {
    enabled: true
  }
)

feature_api.set_organization_features(set_request)
puts "Features updated"

​
Example: Check Feature Inheritance

# Check system defaults
system_features = feature_api.get_system_features({})
puts "System: login_default_org = #{system_features.login_default_org.enabled}"

# Check instance overrides
instance_request = Zitadel::Client::FeatureServiceGetInstanceFeaturesRequest.new
instance_features = feature_api.get_instance_features(instance_request)
puts "Instance: login_default_org = #{instance_features.login_default_org.enabled}"

# Check organization overrides
org_request = Zitadel::Client::FeatureServiceGetOrganizationFeaturesRequest.new(
  organization_id: 'org_123'
)
org_features = feature_api.get_organization_features(org_request)
puts "Organization: login_default_org = #{org_features.login_default_org.enabled}"

​
Example: Bulk Feature Management

# Reset all features for an organization
reset_request = Zitadel::Client::FeatureServiceResetOrganizationFeaturesRequest.new(
  organization_id: 'org_123'
)

feature_api.reset_organization_features(reset_request)
puts "All features reset to instance defaults"

# Set new feature configuration
set_request = Zitadel::Client::FeatureServiceSetOrganizationFeaturesRequest.new(
  organization_id: 'org_123',
  login_default_org: { enabled: true },
  user_schema: { enabled: true }
)

feature_api.set_organization_features(set_request)
puts "New features configured"

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us