Creating and verifying a domain

Domains can be added and verified under an organization by an administrator. In order to enable this feature, go to the Clerk Dashboard and navigate to the Organizations Settings(opens in a new tab) page. Toggle on Verified domains. The only parameter needed to create an organization domain is the name.

Domains can be verified through an email verification code sent to an email that matches the domain. If the administrator 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.

Default role

When enabling the verified domains feature, you are also required to define which role will be assigned to the user that will receive the organization invitation or organization suggestions in order to join your organization.

You can choose any of the available organization roles of your instance.

You can't delete an organization role if it's used as the verified domain's default role.

To specify the verified domain's default role, in the Clerk Dashboard, go to the Organizations Settings(opens in a new tab) page.

Enrollment modes

Once a domain is created and verified, an administrator can choose between two enrollment modes to enable new ways for users to join organizations.

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.

Usage


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

Last updated on January 5, 2024