Verified domains

Verified domains can be used to streamline enrollment into an organization. For example, if the domain @clerk.com is verified, any user with an email address ending in @clerk.com can be automatically invited or be suggested to join an organization with that domain. This feature is useful for organizations that want to restrict membership to users with specific email domains.

A verified domain cannot be a disposable domain or common email provider. For example, you cannot create a verified domain for @gmail.com.

Enable verified domains

Enabling verified domains applies to all organizations and cannot currently be managed on a per-organization basis.

In order to enable this feature:

1. Navigate to the Clerk Dashboard
2. In the navigation sidebar, select Organizations Settings.
3. In the Verified domains section, check the Enable verified domains checkbox.
4. The following settings will appear:

• Enrollment mode - Choose between Automatic invitation and Automatic suggestion.
• Default role - Choose the default role for users who join the organization through a verified domain.

Enrollment mode

You can enable the following enrollment modes to be available for your application:

• Automatic invitation - During sign-up, a user will receive an invitation for the organization if their email's domain matches the verified domain. The user will join the organization if they accept the automatic invitation.
• Automatic suggestion - During sign-up, a user will receive a suggestion for the organization if their email's domain matches the verified domain. The user can request to join, and an administrator must accept this request before the user can join the organization.

Once a domain is added and verified in your organization, the user will have the option to select an enrollment mode from those you made available.

Default role

Once verified domains are enabled, you are required to define which role will be assigned to the user that will receive the organization invitation or organization suggestion in order to join your organization.

By default, the options are "Member" and "Admin". However, you can also create custom roles for your organization.

Adding and verifying domains

Domains can be added and verified under an organization by any user with the org:sys_domains:manage permission. By default, admins have this permission. The easiest way to add and verify domains is by using Clerk's [<OrganizationSwitcher />] component. In the General tab, there will be a Verified domains section.

Domains can be verified through an email verification code sent to an email that matches the domain. If the user adding the domain already has a verified email using that domain in their account, the domain will be automatically verified.

An application instance may only have one verified domain of the same name, and an organization may only have one domain of the same name (verified or unverified).

You can create up to 10 domains per organization to meet your needs. If you need more than 10 domains, reach out to support@clerk.dev.

Custom flow

If Clerk's [<OrganizationSwitcher />] does not meet your specific needs or if you require more control over the logic, you can use the Clerk API to add and verify a domain and update the domain's enrollment mode. Here's an example of how you can do this:

const { organization, domains } = useOrganization();

// create domain
const domain = await organization.createDomain("example.com")

// prepare email verification
domain.prepareAffiliationVerification({ affiliationEmailAddress: "foo@example.com" })

// attempt email verification
domain.attemptAffiliationVerification({ code: "123456" })

// update domain enrollment mode
domain.updateEnrollmentMode({ enrollmentMode: "automatic_invitation" })