Skip to main content

​
Overview

The InstanceServiceApi provides methods for managing Zitadel instances, including instance lifecycle, custom domains, and trusted domains. Most methods require system-level permissions.

​
Initialize the API

require 'zitadel/client'

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

instance_api = Zitadel::Client::Api::InstanceServiceApi.new(client)

​
Instance Management

Returns the instance in the current context or by its ID.Required permissions:
  • iam.read (for current instance)
  • system.instance.read (for specific instance ID)
request = Zitadel::Client::InstanceServiceGetInstanceRequest.new(
  instance_id: 'instance_123' # Optional
)

response = instance_api.get_instance(request)

puts "Instance ID: #{response.instance.id}"
puts "Instance Name: #{response.instance.name}"
puts "Default Org ID: #{response.instance.default_org_id}"
Lists instances matching the given query. Requires system level permissions.Required permission: system.instance.read
request = Zitadel::Client::InstanceServiceListInstancesRequest.new(
  query: {
    limit: 50,
    offset: 0
  },
  queries: [{
    instance_id_query: {
      id: 'instance',
      method: 'TEXT_QUERY_METHOD_CONTAINS'
    }
  }]
)

response = instance_api.list_instances(request)
response.result.each do |instance|
  puts "Instance: #{instance.name} (#{instance.id})"
end
Updates instance’s name in the current context or by its ID.Required permissions:
  • iam.write (for current instance)
  • system.instance.write (for specific instance ID)
request = Zitadel::Client::InstanceServiceUpdateInstanceRequest.new(
  instance_id: 'instance_123', # Optional
  name: 'Updated Instance Name'
)

response = instance_api.update_instance(request)
Deletes an instance with the given ID. Requires system level permissions.Required permission: system.instance.delete
request = Zitadel::Client::InstanceServiceDeleteInstanceRequest.new(
  instance_id: 'instance_123'
)

response = instance_api.delete_instance(request)

​
Custom Domain Management

Adds a custom domain to the instance. The domain must be unique across all instances and will be used to route requests.Required permission: system.domain.write
request = Zitadel::Client::InstanceServiceAddCustomDomainRequest.new(
  instance_id: 'instance_123',
  domain: 'auth.mycompany.com'
)

response = instance_api.add_custom_domain(request)
puts "Domain added: #{response.domain}"
Lists custom domains of the instance.Required permissions:
  • iam.read (for current instance)
  • system.instance.read (for specific instance ID)
request = Zitadel::Client::InstanceServiceListCustomDomainsRequest.new(
  instance_id: 'instance_123' # Optional
)

response = instance_api.list_custom_domains(request)
response.result.each do |domain|
  puts "Domain: #{domain.domain}, Primary: #{domain.is_primary}"
end
Removes a custom domain from the instance. This will stop routing requests from this domain.Required permission: system.domain.write
request = Zitadel::Client::InstanceServiceRemoveCustomDomainRequest.new(
  instance_id: 'instance_123',
  domain: 'auth.mycompany.com'
)

response = instance_api.remove_custom_domain(request)

​
Trusted Domain Management

Adds a trusted domain to the instance. Trusted domains can be used in API responses like OIDC discovery and email templates.Required permissions:
  • iam.write (for current instance)
  • system.instance.write (for specific instance ID)
request = Zitadel::Client::InstanceServiceAddTrustedDomainRequest.new(
  instance_id: 'instance_123', # Optional
  domain: 'login.mycompany.com'
)

response = instance_api.add_trusted_domain(request)
puts "Trusted domain added: #{response.domain}"
Lists trusted domains of the instance.Required permissions:
  • iam.read (for current instance)
  • system.instance.read (for specific instance ID)
request = Zitadel::Client::InstanceServiceListTrustedDomainsRequest.new(
  instance_id: 'instance_123' # Optional
)

response = instance_api.list_trusted_domains(request)
response.result.each do |domain|
  puts "Trusted Domain: #{domain}"
end
Removes a trusted domain from the instance.Required permissions:
  • iam.write (for current instance)
  • system.instance.write (for specific instance ID)
request = Zitadel::Client::InstanceServiceRemoveTrustedDomainRequest.new(
  instance_id: 'instance_123', # Optional
  domain: 'login.mycompany.com'
)

response = instance_api.remove_trusted_domain(request)

​
Custom vs Trusted Domains

​
Custom Domains

  • Must be unique across all instances
  • Used to route requests to the instance
  • Require system-level permissions
  • Example: auth.mycompany.com

​
Trusted Domains

  • Can be shared across instances
  • Used in API responses (OIDC discovery, emails)
  • Useful for proxy setups and custom login UIs
  • Example: login.mycompany.com

​
Example: Set Up Custom Domain

# Add custom domain
add_request = Zitadel::Client::InstanceServiceAddCustomDomainRequest.new(
  instance_id: 'instance_123',
  domain: 'auth.mycompany.com'
)

add_response = instance_api.add_custom_domain(add_request)
puts "Added domain: #{add_response.domain}"

# List all custom domains
list_request = Zitadel::Client::InstanceServiceListCustomDomainsRequest.new(
  instance_id: 'instance_123'
)

list_response = instance_api.list_custom_domains(list_request)
list_response.result.each do |domain|
  puts "Domain: #{domain.domain}"
  puts "  Primary: #{domain.is_primary}"
  puts "  Generated: #{domain.is_generated}"
end

​
Example: Configure Trusted Domains for Proxy Setup

# Add trusted domain for custom login UI
trusted_request = Zitadel::Client::InstanceServiceAddTrustedDomainRequest.new(
  domain: 'login.mycompany.com'
)

trusted_response = instance_api.add_trusted_domain(trusted_request)

# Now this domain can be used in:
# - OIDC discovery endpoints
# - Email templates
# - Redirect URIs
# - CORS origins

​
Example: Multi-Instance Management

# List all instances
request = Zitadel::Client::InstanceServiceListInstancesRequest.new(
  query: {
    limit: 100
  }
)

response = instance_api.list_instances(request)

response.result.each do |instance|
  puts "Instance: #{instance.name}"
  puts "  ID: #{instance.id}"
  puts "  State: #{instance.state}"
  
  # Get domains for each instance
  domains_request = Zitadel::Client::InstanceServiceListCustomDomainsRequest.new(
    instance_id: instance.id
  )
  
  domains = instance_api.list_custom_domains(domains_request)
  domains.result.each do |domain|
    puts "  Domain: #{domain.domain}"
  end
end

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us