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
