Overview
Organization models represent organization entities in Zitadel. Organizations are used to logically separate resources and provide multi-tenancy capabilities.
OrganizationServiceOrganization
The main organization model representing an organization entity.
Unique identifier of the organization
details
OrganizationServiceDetails
Metadata about the organization resource including sequence number and timestamps
state
OrganizationServiceOrganizationState
Current state of the organization (e.g., ACTIVE, INACTIVE)
Primary domain used in the organization
Example JSON
{
"id": "987654321",
"name": "ACME Corporation",
"primaryDomain": "acme.com",
"state": "ORGANIZATION_STATE_ACTIVE",
"details": {
"sequence": "1234",
"creationDate": "2024-01-15T10:30:00Z",
"changeDate": "2024-03-01T14:20:00Z",
"resourceOwner": "987654321"
}
}
Example Usage
organization = response.organization
puts "Organization: #{organization.name}"
puts "ID: #{organization.id}"
puts "Primary Domain: #{organization.primary_domain}"
puts "State: #{organization.state}"
if organization.state == 'ORGANIZATION_STATE_ACTIVE'
puts "Organization is active"
else
puts "Organization is not active"
end
OrganizationServiceDomain
Represents a domain associated with an organization.
Unique identifier of the organization the domain belongs to
Fully qualified domain name
Whether the domain has been verified
Whether this domain is the primary domain of the organization
validation_type
OrganizationServiceDomainValidationType
Type of validation used for domain verification (e.g., DNS, HTTP)
Example JSON
{
"organizationId": "987654321",
"domain": "acme.com",
"isVerified": true,
"isPrimary": true,
"validationType": "DOMAIN_VALIDATION_TYPE_DNS"
}
Example Usage
domain = response.domain
puts "Domain: #{domain.domain}"
puts "Organization ID: #{domain.organization_id}"
puts "Verified: #{domain.is_verified}"
puts "Primary: #{domain.is_primary}"
puts "Validation Type: #{domain.validation_type}"
if domain.is_verified
if domain.is_primary
puts "This is the primary verified domain"
else
puts "This is a verified domain"
end
else
puts "Domain verification pending"
end
OrganizationServiceAdmin
Represents an administrator assigned to an organization.
Unique identifier of the user who is an admin
List of admin roles assigned to the user
Email address of the admin user
Display name of the admin user
Example Usage
admins = response.admins
admins.each do |admin|
puts "Admin: #{admin.display_name} (#{admin.email})"
puts "User ID: #{admin.user_id}"
puts "Roles: #{admin.roles.join(', ')}"
puts "---"
end
OrganizationServiceDetails
Metadata about organization resources.
Sequence number for optimistic locking
Timestamp when the resource was created
Timestamp when the resource was last modified
ID of the resource owner (typically the organization ID)
Example Usage
details = organization.details
if details
puts "Created: #{details.creation_date.strftime('%Y-%m-%d')}"
puts "Last Modified: #{details.change_date.strftime('%Y-%m-%d %H:%M:%S')}"
puts "Sequence: #{details.sequence}"
puts "Owner: #{details.resource_owner}"
end
Working with Organizations
Listing Organization Domains
response = client.organization_service.list_organization_domains(
organization_id: org_id
)
response.domains.each do |domain|
status = []
status << "verified" if domain.is_verified
status << "primary" if domain.is_primary
status_str = status.any? ? " (#{status.join(', ')})" : ""
puts "#{domain.domain}#{status_str}"
end
Finding Primary Domain
def find_primary_domain(organization_id)
response = client.organization_service.list_organization_domains(
organization_id: organization_id
)
response.domains.find { |d| d.is_primary }
end
primary = find_primary_domain(org_id)
if primary
puts "Primary domain: #{primary.domain}"
else
puts "No primary domain configured"
end
Checking Organization State
def organization_active?(organization)
organization.state == 'ORGANIZATION_STATE_ACTIVE'
end
if organization_active?(organization)
puts "Organization '#{organization.name}' is active"
else
puts "Organization '#{organization.name}' is not active"
puts "Current state: #{organization.state}"
end
Validating Domain Verification
def all_domains_verified?(organization_id)
response = client.organization_service.list_organization_domains(
organization_id: organization_id
)
response.domains.all? { |domain| domain.is_verified }
end
if all_domains_verified?(org_id)
puts "All domains are verified"
else
puts "Some domains need verification"
end
def get_organization_info(organization)
info = {
name: organization.name,
id: organization.id,
domain: organization.primary_domain,
active: organization.state == 'ORGANIZATION_STATE_ACTIVE'
}
if organization.details
info[:created] = organization.details.creation_date
info[:modified] = organization.details.change_date
end
info
end
org_info = get_organization_info(organization)
puts "Organization: #{org_info[:name]}"
puts "Domain: #{org_info[:domain]}"
puts "Status: #{org_info[:active] ? 'Active' : 'Inactive'}"
puts "Created: #{org_info[:created].strftime('%Y-%m-%d')}" if org_info[:created]
Common Organization Patterns
Multi-Tenant Context
# Store organization context for multi-tenant applications
class OrganizationContext
attr_reader :organization
def initialize(organization)
@organization = organization
end
def organization_id
@organization.id
end
def organization_name
@organization.name
end
def primary_domain
@organization.primary_domain
end
def active?
@organization.state == 'ORGANIZATION_STATE_ACTIVE'
end
end
context = OrganizationContext.new(organization)
puts "Working in organization: #{context.organization_name}"
Domain-Based Organization Lookup
def find_organization_by_domain(email_or_domain)
domain = email_or_domain.include?('@') ? email_or_domain.split('@').last : email_or_domain
# Search for organization with matching domain
response = client.organization_service.list_organizations
response.organizations.find do |org|
org.primary_domain == domain
end
end
org = find_organization_by_domain('[email protected]')
if org
puts "Found organization: #{org.name}"
else
puts "No organization found for domain"
end
These models are used in conjunction with organization models:
OrganizationServiceDetails - Resource metadata
OrganizationServiceOrganizationState - Enum for organization states
OrganizationServiceDomainValidationType - Enum for domain validation types
OrganizationServiceAdmin - Organization administrator information
OrganizationServiceGender - Gender enum used in organization user creation
OrganizationServiceIDPLink - Identity provider link information
Next Steps