Skip to main content
Deprecated: Please move to the corresponding endpoints under Instance Service v2. This service will be removed in the next major version of ZITADEL.

​
Overview

The BetaInstanceServiceApi provides methods for managing ZITADEL instances, including instance lifecycle, custom domains, and trusted domains.

​
Initialization

require 'zitadel/client'

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

instance_service = Zitadel::Client::Api::BetaInstanceServiceApi.new(client)
Most instance management operations require system-level permissions.

​
Key Methods

​
Instance Management

Retrieves information about the current instance.
request = Zitadel::Client::Models::BetaInstanceServiceGetInstanceRequest.new

response = instance_service.get_instance(request)

puts "Instance ID: #{response.instance.id}"
puts "Instance name: #{response.instance.name}"
puts "State: #{response.instance.state}"
puts "Created: #{response.instance.creation_date}"
Required Permission: iam.readReturns: BetaInstanceServiceGetInstanceResponse
Lists instances matching the query (system operators only).
request = Zitadel::Client::Models::BetaInstanceServiceListInstancesRequest.new(
  queries: [
    {
      domain_query: {
        domain: 'example.com'
      }
    }
  ],
  limit: 100
)

response = instance_service.list_instances(request)

response.result.each do |instance|
  puts "Instance: #{instance.name} (#{instance.id})"
  puts "  Domains: #{instance.domains.join(', ')}"
end
Required Permission: system.instance.readReturns: BetaInstanceServiceListInstancesResponse
Changes the instance name.
request = Zitadel::Client::Models::BetaInstanceServiceUpdateInstanceRequest.new(
  instance_id: 'current',
  name: 'Production Instance'
)

instance_service.update_instance(request)
Required Permission: iam.writeReturns: BetaInstanceServiceUpdateInstanceResponse
Permanently deletes an instance and all its data.
request = Zitadel::Client::Models::BetaInstanceServiceDeleteInstanceRequest.new(
  instance_id: '123456789'
)

instance_service.delete_instance(request)
This operation is irreversible and deletes all instance data!
Required Permission: system.instance.deleteReturns: BetaInstanceServiceDeleteInstanceResponse

​
Custom Domain Management

Adds a custom domain to the instance.
request = Zitadel::Client::Models::BetaInstanceServiceAddCustomDomainRequest.new(
  domain: 'auth.example.com'
)

response = instance_service.add_custom_domain(request)

puts "Domain added: #{response.domain}"
puts "Verification: #{response.validation_type}"
Required Permission: system.domain.writeReturns: BetaInstanceServiceAddCustomDomainResponse
Returns all custom domains configured for the instance.
request = Zitadel::Client::Models::BetaInstanceServiceListCustomDomainsRequest.new

response = instance_service.list_custom_domains(request)

response.result.each do |domain|
  puts "Domain: #{domain.domain}"
  puts "  Verified: #{domain.is_verified}"
  puts "  Primary: #{domain.is_primary}"
  puts "  Generated: #{domain.is_generated}"
end
Required Permission: iam.readReturns: BetaInstanceServiceListCustomDomainsResponse
Removes a custom domain from the instance.
request = Zitadel::Client::Models::BetaInstanceServiceRemoveCustomDomainRequest.new(
  domain: 'auth.example.com'
)

instance_service.remove_custom_domain(request)
Required Permission: system.domain.writeReturns: BetaInstanceServiceRemoveCustomDomainResponse

​
Trusted Domain Management

Adds a domain to the trusted domains list for CORS and iframe embedding.
request = Zitadel::Client::Models::BetaInstanceServiceAddTrustedDomainRequest.new(
  domain: 'myapp.example.com'
)

instance_service.add_trusted_domain(request)
Required Permission: iam.writeReturns: BetaInstanceServiceAddTrustedDomainResponse
Returns all trusted domains for the instance.
request = Zitadel::Client::Models::BetaInstanceServiceListTrustedDomainsRequest.new

response = instance_service.list_trusted_domains(request)

response.trusted_domains.each do |domain|
  puts "Trusted domain: #{domain}"
end
Required Permission: iam.readReturns: BetaInstanceServiceListTrustedDomainsResponse
Removes a domain from the trusted domains list.
request = Zitadel::Client::Models::BetaInstanceServiceRemoveTrustedDomainRequest.new(
  domain: 'myapp.example.com'
)

instance_service.remove_trusted_domain(request)
Required Permission: iam.writeReturns: BetaInstanceServiceRemoveTrustedDomainResponse

​
Use Cases

​
Setting Up Custom Domain

# 1. Add custom domain
request = Zitadel::Client::Models::BetaInstanceServiceAddCustomDomainRequest.new(
  domain: 'auth.mycompany.com'
)

response = instance_service.add_custom_domain(request)

puts "Set up DNS:"
puts "Type: #{response.validation.type}"
puts "Record: #{response.validation.record}"
puts "Value: #{response.validation.value}"

# 2. User sets up DNS record

# 3. Domain verification happens automatically

# 4. Check verification status
request = Zitadel::Client::Models::BetaInstanceServiceListCustomDomainsRequest.new
domains = instance_service.list_custom_domains(request)

domain = domains.result.find { |d| d.domain == 'auth.mycompany.com' }
if domain.is_verified
  puts "Domain verified and ready to use!"
else
  puts "Waiting for DNS propagation..."
end

​
Managing Trusted Domains for CORS

# Add multiple trusted domains
application_domains = [
  'app.example.com',
  'dashboard.example.com',
  'mobile.example.com'
]

application_domains.each do |domain|
  request = Zitadel::Client::Models::BetaInstanceServiceAddTrustedDomainRequest.new(
    domain: domain
  )
  
  begin
    instance_service.add_trusted_domain(request)
    puts "Added trusted domain: #{domain}"
  rescue Zitadel::Client::ApiError => e
    puts "Error adding #{domain}: #{e.message}"
  end
end

# List all trusted domains
request = Zitadel::Client::Models::BetaInstanceServiceListTrustedDomainsRequest.new
response = instance_service.list_trusted_domains(request)

puts "All trusted domains:"
response.trusted_domains.each { |d| puts "  - #{d}" }

​
Instance Information Dashboard

def instance_dashboard
  # Get instance details
  instance_req = Zitadel::Client::Models::BetaInstanceServiceGetInstanceRequest.new
  instance = instance_service.get_instance(instance_req).instance
  
  # Get custom domains
  domains_req = Zitadel::Client::Models::BetaInstanceServiceListCustomDomainsRequest.new
  domains = instance_service.list_custom_domains(domains_req)
  
  # Get trusted domains
  trusted_req = Zitadel::Client::Models::BetaInstanceServiceListTrustedDomainsRequest.new
  trusted = instance_service.list_trusted_domains(trusted_req)
  
  {
    instance: {
      id: instance.id,
      name: instance.name,
      state: instance.state,
      created: instance.creation_date
    },
    custom_domains: domains.result.map { |d|
      {
        domain: d.domain,
        verified: d.is_verified,
        primary: d.is_primary
      }
    },
    trusted_domains: trusted.trusted_domains
  }
end

​
Multi-Instance Management (System Operators)

# List all instances
request = Zitadel::Client::Models::BetaInstanceServiceListInstancesRequest.new(
  limit: 100
)

response = instance_service.list_instances(request)

puts "Total instances: #{response.details.total_result}"

response.result.each do |instance|
  puts "\nInstance: #{instance.name}"
  puts "  ID: #{instance.id}"
  puts "  State: #{instance.state}"
  puts "  Created: #{instance.creation_date}"
  puts "  Domains: #{instance.domains.join(', ')}"
end

​
Domain Verification

Custom domains must be verified before use:

​
DNS Verification

# Add domain returns verification instructions
response = instance_service.add_custom_domain(request)

# Create DNS TXT record:
# Name: _zitadel-challenge.auth.example.com
# Value: response.validation.value

​
HTTP Verification

# Alternative: HTTP file verification
# Place file at: http://auth.example.com/.well-known/zitadel-challenge
# Content: response.validation.value

​
Instance States

  • STATE_ACTIVE - Instance is running normally
  • STATE_INACTIVE - Instance is temporarily disabled
  • STATE_DELETED - Instance is deleted (tombstone)

​
Required Permissions

  • iam.read - Read instance information
  • iam.write - Modify instance settings
  • system.instance.read - List all instances (system)
  • system.instance.delete - Delete instances (system)
  • system.domain.write - Manage custom domains (system)

​
Migration Guide

To migrate to Instance Service v2:
  1. Replace BetaInstanceServiceApi with InstanceServiceV2Api
  2. Update request/response models
  3. Review domain management changes
  4. Test verification flows

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us