Skip to main content
Deprecated: Please move to the corresponding endpoints under Organization Service v2. This service will be removed in the next major version of ZITADEL.

​
Overview

The BetaOrganizationServiceApi provides methods for managing organizations, including creation, domains, metadata, and lifecycle operations.

​
Initialization

require 'zitadel/client'

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

org_service = Zitadel::Client::Api::BetaOrganizationServiceApi.new(client)

​
Key Methods

​
Organization Management

​
beta_organization_service_create_organization_request
object
required
Request containing organization details
request = Zitadel::Client::Models::BetaOrganizationServiceCreateOrganizationRequest.new(
  name: 'Acme Corporation'
)

response = org_service.create_organization(request)
puts "Organization ID: #{response.organization_id}"
Required Permission: org.createReturns: BetaOrganizationServiceCreateOrganizationResponse
​
beta_organization_service_update_organization_request
object
required
Request with organization ID and new name
request = Zitadel::Client::Models::BetaOrganizationServiceUpdateOrganizationRequest.new(
  organization_id: '123456789',
  name: 'Acme Corp'
)

org_service.update_organization(request)
Required Permission: org.write
​
beta_organization_service_list_organizations_request
object
required
Request with search filters
request = Zitadel::Client::Models::BetaOrganizationServiceListOrganizationsRequest.new(
  limit: 50
)

response = org_service.list_organizations(request)
response.result.each do |org|
  puts "Organization: #{org.name}"
end
Required Permission: org.read

​
Organization Lifecycle

Sets organization state to active. Users can log in again.
request = Zitadel::Client::Models::BetaOrganizationServiceActivateOrganizationRequest.new(
  organization_id: '123456789'
)

org_service.activate_organization(request)
Required Permission: org.write
Sets organization state to deactivated. Users cannot log in.
request = Zitadel::Client::Models::BetaOrganizationServiceDeactivateOrganizationRequest.new(
  organization_id: '123456789'
)

org_service.deactivate_organization(request)
Required Permission: org.write
Deletes the organization and all its resources (users, projects, grants).
request = Zitadel::Client::Models::BetaOrganizationServiceDeleteOrganizationRequest.new(
  organization_id: '123456789'
)

org_service.delete_organization(request)
Required Permission: org.delete

​
Domain Management

Adds a new domain to identify users belonging to the organization.
request = Zitadel::Client::Models::BetaOrganizationServiceAddOrganizationDomainRequest.new(
  organization_id: '123456789',
  domain: 'acme.com'
)

org_service.add_organization_domain(request)
Required Permission: org.write
Returns all registered domains for the organization.
request = Zitadel::Client::Models::BetaOrganizationServiceListOrganizationDomainsRequest.new(
  organization_id: '123456789'
)

response = org_service.list_organization_domains(request)
response.result.each do |domain|
  puts "Domain: #{domain.domain_name} (verified: #{domain.is_verified})"
end
Required Permission: org.read
Generates a verification file for DNS or HTTP challenge.
request = Zitadel::Client::Models::BetaOrganizationServiceGenerateOrganizationDomainValidationRequest.new(
  organization_id: '123456789',
  domain: 'acme.com',
  type: 'DNS' # or 'HTTP'
)

response = org_service.generate_organization_domain_validation(request)
puts "Validation token: #{response.token}"
Required Permission: org.write
Verifies domain ownership after setting up DNS/HTTP challenge.
request = Zitadel::Client::Models::BetaOrganizationServiceVerifyOrganizationDomainRequest.new(
  organization_id: '123456789',
  domain: 'acme.com'
)

org_service.verify_organization_domain(request)
Required Permission: org.write
Removes a domain from the organization.
request = Zitadel::Client::Models::BetaOrganizationServiceDeleteOrganizationDomainRequest.new(
  organization_id: '123456789',
  domain: 'acme.com'
)

org_service.delete_organization_domain(request)
Required Permission: org.write

​
Metadata Management

Adds or updates metadata for the organization (value must be base64 encoded).
request = Zitadel::Client::Models::BetaOrganizationServiceSetOrganizationMetadataRequest.new(
  organization_id: '123456789',
  key: 'department',
  value: Base64.encode64('Engineering')
)

org_service.set_organization_metadata(request)
Required Permission: org.write
Returns all metadata entries for the organization.
request = Zitadel::Client::Models::BetaOrganizationServiceListOrganizationMetadataRequest.new(
  organization_id: '123456789'
)

response = org_service.list_organization_metadata(request)
response.result.each do |metadata|
  puts "#{metadata.key}: #{Base64.decode64(metadata.value)}"
end
Required Permission: org.read
Deletes a specific metadata entry.
request = Zitadel::Client::Models::BetaOrganizationServiceDeleteOrganizationMetadataRequest.new(
  organization_id: '123456789',
  key: 'department'
)

org_service.delete_organization_metadata(request)
Required Permission: org.write

​
Required Permissions

  • org.read - Read organization information
  • org.write - Modify organization data
  • org.create - Create new organizations
  • org.delete - Delete organizations

​
Migration Guide

To migrate to Organization Service v2:
  1. Replace BetaOrganizationServiceApi with OrganizationServiceV2Api
  2. Update model references to v2 versions
  3. Review API response structure changes
  4. Test domain verification flows

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us