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. The role assigned to this user will be the role set as the Default role in the organization settings page. The verified domains 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.

The easiest way to add and verify domains, and manage all settings related to verified domains is to use Clerk's <OrganizationSwitcher /> component.

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. In the Clerk Dashboard, navigate to the Organizations Settings⁠ page.
2. In the Verified domains section, enable Enable verified domains.
3. The following setting will appear:
   • Enrollment mode - Automatic invitation and Automatic suggestion.

Enrollment mode

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

• Automatic invitation - Users are automatically invited to join the organization when they sign-up and can join anytime.
• Automatic suggestion - Users receive a suggestion to request to join, but must be approved by an admin before they are able to join the organization.

Then, in your application, when a user with the org:sys_domains:manage permission has added and verified a domain, they can enable an enrollment mode. Only one enrollment mode can be enabled for a verified domain at a time.

Automatic invitations

After sign-up, a user will receive an invitation for the organization if their email's domain matches the verified domain. If your app uses the <OrganizationSwitcher /> component, the user will see a notification on the component. When they open the component, they will see a Join button next to the organization they were invited to. Selecting the button will accept the invitation and the user will instantly be added as a member of the organization.

Automatic suggestions

After sign-up, a user will receive a suggestion for the organization if their email's domain matches the verified domain. If your app uses the <OrganizationSwitcher /> component, the user will see a Request to join button next to the organization. Selecting the button will send a membership request to the organization.

Membership requests

Membership requests are requests from users who saw an organization suggestion and requested to join an organization. Membership requests are only available for organizations that have the Verified domains feature enabled and the Automatic suggestions feature enabled in both the Dashboard and for the specific domain.

When a user sends an organization membership request, users with the org:sys_memberships:manage permission (by default, admins) will see a notification on their <OrganizationSwitcher /> component. They will need to accept the request before the user can join the organization.

Add and verify 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. To add and verify domains in the <OrganizationSwitcher /> component, select 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, contact support⁠.

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' })