Documentation Index
Fetch the complete documentation index at: https://mintlify.com/zitadel/client-ruby/llms.txt
Use this file to discover all available pages before exploring further.
The Organization Service provides methods to create, manage, and configure organizations within your Zitadel instance.
Overview
The OrganizationServiceApi class provides methods for:
- Creating and managing organizations
- Managing organization domains and verification
- Organization state management (activate/deactivate)
- Organization metadata operations
- Listing and searching organizations
Initialization
require 'zitadel/client'
api_client = Zitadel::Client::ApiClient.new
api_client.config.access_token = 'YOUR_ACCESS_TOKEN'
org_service = Zitadel::Client::Api::OrganizationServiceApi.new(api_client)
Organization Management
add_organization
Create a new organization with an administrative user.
request = Zitadel::Client::OrganizationServiceAddOrganizationRequest.new(
name: 'Acme Corporation',
admins: [
Zitadel::Client::OrganizationServiceAdmin.new(
user_id: 'user_123',
roles: ['ORG_OWNER']
)
]
)
response = org_service.add_organization(request)
puts "Organization ID: #{response.organization_id}"
The name of the organization
List of administrative users for the organization
The unique identifier of the created organization
list_organizations
List organizations with filtering and pagination.
request = Zitadel::Client::OrganizationServiceListOrganizationsRequest.new(
query: Zitadel::Client::OrganizationServiceListQuery.new(
limit: 50,
offset: 0
),
queries: [
Zitadel::Client::OrganizationServiceSearchQuery.new(
name_query: Zitadel::Client::OrganizationServiceOrganizationNameQuery.new(
name: 'Acme',
method: 'TEXT_QUERY_METHOD_CONTAINS'
)
)
]
)
response = org_service.list_organizations(request)
response.result.each do |org|
puts "Organization: #{org.name}"
end
update_organization
Update organization details.
request = Zitadel::Client::OrganizationServiceUpdateOrganizationRequest.new(
organization_id: 'org_123',
name: 'Acme Corporation Updated'
)
response = org_service.update_organization(request)
activate_organization
Activate a deactivated organization. Users will be able to log in again.
request = Zitadel::Client::OrganizationServiceActivateOrganizationRequest.new(
organization_id: 'org_123'
)
response = org_service.activate_organization(request)
The ID of the organization to activate
deactivate_organization
Deactivate an organization. Users will not be able to log in.
request = Zitadel::Client::OrganizationServiceDeactivateOrganizationRequest.new(
organization_id: 'org_123'
)
response = org_service.deactivate_organization(request)
delete_organization
Permanently delete an organization.
request = Zitadel::Client::OrganizationServiceDeleteOrganizationRequest.new(
organization_id: 'org_123'
)
response = org_service.delete_organization(request)
Domain Management
add_organization_domain
Add a new domain to an organization. Domains are used to identify which organization a user belongs to.
request = Zitadel::Client::OrganizationServiceAddOrganizationDomainRequest.new(
organization_id: 'org_123',
domain: 'acme.com'
)
response = org_service.add_organization_domain(request)
details
OrganizationServiceDetails
Metadata about the operation
generate_organization_domain_validation
Generate a validation token for domain verification.
request = Zitadel::Client::OrganizationServiceGenerateOrganizationDomainValidationRequest.new(
organization_id: 'org_123',
domain: 'acme.com',
type: 'DOMAIN_VALIDATION_TYPE_DNS'
)
response = org_service.generate_organization_domain_validation(request)
puts "Validation token: #{response.token}"
puts "Validation URL: #{response.url}"
Validation type: DOMAIN_VALIDATION_TYPE_DNS or DOMAIN_VALIDATION_TYPE_HTTP
The validation token to add to DNS or HTTP endpoint
The URL where the token should be accessible (for HTTP validation)
verify_organization_domain
Verify a domain after adding the validation token.
request = Zitadel::Client::OrganizationServiceVerifyOrganizationDomainRequest.new(
organization_id: 'org_123',
domain: 'acme.com'
)
response = org_service.verify_organization_domain(request)
list_organization_domains
List all domains for an organization.
request = Zitadel::Client::OrganizationServiceListOrganizationDomainsRequest.new(
organization_id: 'org_123',
query: Zitadel::Client::OrganizationServiceListQuery.new(
limit: 100
)
)
response = org_service.list_organization_domains(request)
response.result.each do |domain|
puts "Domain: #{domain.domain_name}, Verified: #{domain.is_verified}"
end
delete_organization_domain
Remove a domain from an organization.
request = Zitadel::Client::OrganizationServiceDeleteOrganizationDomainRequest.new(
organization_id: 'org_123',
domain: 'acme.com'
)
response = org_service.delete_organization_domain(request)
request = Zitadel::Client::OrganizationServiceSetOrganizationMetadataRequest.new(
organization_id: 'org_123',
key: 'industry',
value: 'Technology'.bytes
)
response = org_service.set_organization_metadata(request)
The metadata value as bytes
request = Zitadel::Client::OrganizationServiceListOrganizationMetadataRequest.new(
organization_id: 'org_123',
query: Zitadel::Client::OrganizationServiceListQuery.new(
limit: 100
)
)
response = org_service.list_organization_metadata(request)
response.result.each do |metadata|
puts "#{metadata.key}: #{metadata.value}"
end
request = Zitadel::Client::OrganizationServiceDeleteOrganizationMetadataRequest.new(
organization_id: 'org_123',
key: 'industry'
)
response = org_service.delete_organization_metadata(request)
Complete Example
require 'zitadel/client'
api_client = Zitadel::Client::ApiClient.new
api_client.config.access_token = ENV['ZITADEL_ACCESS_TOKEN']
org_service = Zitadel::Client::Api::OrganizationServiceApi.new(api_client)
begin
# Create organization
create_request = Zitadel::Client::OrganizationServiceAddOrganizationRequest.new(
name: 'Acme Corporation',
admins: [
Zitadel::Client::OrganizationServiceAdmin.new(
user_id: 'user_123',
roles: ['ORG_OWNER']
)
]
)
org_response = org_service.add_organization(create_request)
org_id = org_response.organization_id
puts "Created organization: #{org_id}"
# Add domain
domain_request = Zitadel::Client::OrganizationServiceAddOrganizationDomainRequest.new(
organization_id: org_id,
domain: 'acme.com'
)
org_service.add_organization_domain(domain_request)
# Generate validation
validation_request = Zitadel::Client::OrganizationServiceGenerateOrganizationDomainValidationRequest.new(
organization_id: org_id,
domain: 'acme.com',
type: 'DOMAIN_VALIDATION_TYPE_DNS'
)
validation_response = org_service.generate_organization_domain_validation(validation_request)
puts "Add this TXT record: #{validation_response.token}"
# Set metadata
metadata_request = Zitadel::Client::OrganizationServiceSetOrganizationMetadataRequest.new(
organization_id: org_id,
key: 'industry',
value: 'Technology'.bytes
)
org_service.set_organization_metadata(metadata_request)
rescue Zitadel::Client::ApiError => e
puts "Error: #{e.message}"
end
See Also
