apps/docs/content/guides/manage/console/organizations-overview.mdx
ZITADEL is organized around the idea of multi-tenancy. An Organization is the vessel where your projects and users live. It is comparable to a tenant in a SaaS system or an organizational unit (OU) in a directory-based system.
Key characteristics of Organizations in ZITADEL include:
In a B2B use case, an organization typically represents a business partner who requires their own branding, specific access settings, or distinct federated login providers.
You can use Projects within your organization to manage the security context of closely related components, such as roles, grants, and authorizations for multiple applications. You can set up multiple projects within a single organization.
ZITADEL allows you to give other organizations permission to manage certain aspects of a project within your organization.
For example, you could set up a project with roles that define access to your software, but allow a partner organization to allocate those roles to their own users independently. As a service provider, this allows you to establish a self-service culture for your business customers.
To create a new organization, click on the organizations dropdown in the Management Console and select New organization.
You have two options regarding the initial administrator:
If you want to enable your customers to create organizations themselves, ZITADEL provides a built-in registration form at:
https://$CUSTOM-DOMAIN/ui/login/register/org
The customer simply fills in the organization name and contact details to get started.
On the Default settings page (${CUSTOM_DOMAIN}/ui/console/orgs), you can designate a specific organization as the "Default".
When no specific organization is selected (e.g., during an auth request or via Domain Discovery), users are directed to this default organization for login and self-registration.
Each organization has its own pool of users, covering both users and service accounts. How these users authenticate depends on your domain settings.
By default, if the setting User Loginname must contain orgdomain is disabled, usernames are unique across the entire instance.
If you require usernames to be scoped to the organization (common in multi-tenant setups), you can enable User Loginname must contain orgdomain in your Domain settings. Login names will then follow the format:
{username}@{domainname}.{zitadeldomain}
Example:
If a user has the username john.doe in an organization with the domain acme, the generated login name is:
[email protected]
You can verify your own domain names (e.g., acme.ch) to simplify the user experience. Once verified:
john.doe can log in via [email protected] OR [email protected].An organization can have multiple domain names, but only one is configured as the Organization Domain. The Organization Domain determines:
access_tokens (specifically the preferred_username claim).If the validate Organization Domains setting in Domain Settings is set to true, you must prove ownership of your domain via DNS or HTTP challenge.
Navigate to your Organization Settings.
Select the menu entry Organization Domains.
Click on the domain name you wish to verify. A dialog will appear offering DNS or HTTP challenge methods.
DNS Challenge Example: Create a TXT record with your DNS provider using the value provided by ZITADEL.
Once verified, click Verify.
(Optional) Click Set as primary to make this the default domain for user login names.
Organizations can inherit settings from the instance defaults or override them with specific policies. Settings configured at the Organization level take priority over Default settings.
To apply a custom design (e.g., for a specific B2B customer):
When a user begins the login process, ZITADEL automatically determines the user's organization based on their entered login name and redirects them to the appropriate organization context. Users cannot select their organization manually.
By default, the ZITADEL Login uses the instance default settings. To trigger the specific settings (and branding) of an organization, you must provide the organization scope in your authentication request:
urn:zitadel:iam:org:id:{id}
This value is a reserved scope within ZITADEL.