Skip to main content

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.
id
string
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)
name
string
Name of the organization
primary_domain
string
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.
organization_id
string
Unique identifier of the organization the domain belongs to
domain
string
Fully qualified domain name
is_verified
boolean
Whether the domain has been verified
is_primary
boolean
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.
user_id
string
Unique identifier of the user who is an admin
roles
array<string>
List of admin roles assigned to the user
email
string
Email address of the admin user
display_name
string
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
string
Sequence number for optimistic locking
creation_date
Time
Timestamp when the resource was created
change_date
Time
Timestamp when the resource was last modified
resource_owner
string
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

Organization Display Information

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

Build docs developers (and LLMs) love