Account Linking

Account Linking is a process used by Clerk to ensure a smooth sign-in and sign-up experience using both OAuth and other methods (e.g. username/password). By using the "email address" as the common identifier, Clerk aims to merge accounts whenever possible. This mechanism is triggered when a social provider returns an email address that matches an existing account, assuming a single owner for each email address.

How it works

When a user attempts to sign in or sign up, Clerk first checks the email address provided. If that email address comes from a social provider such as Google or Facebook, Clerk's behavior varies. It considers two main factors: the verification status of the email address, and whether an account with that email address already exists in Clerk's system. Based on these factors, Clerk will attempt to link the OAuth account with any existing Clerk account that shares the same email address.

In the following sections, we'll look at the different scenarios that can occur during this process and explain how Clerk handles each one.

Email address is verified in both OAuth and Clerk

In this scenario, when a user with a verified email address signs in using a social provider that returns a matching verified email address, Clerk links the OAuth account to the existing account and signs the user in. This even applies to password-protected accounts, as the OAuth sign-in process automatically bypasses password verification.

Email address is verified in Clerk but not in OAuth

In this scenario, when a user with a verified email address at Clerk signs in using a social provider that returns a matching but unverified email address, Clerk will initiate a verification process. Once the email address is verified, the OAuth account is linked to the existing one, and the user is signed in.

Email address is not verified in Clerk and not in OAuth

For instances that allow account creation without email verification at sign-up, there is a possibility that an account may be created using an unverified email address, either through OAuth or other methods like username/password.

To allow unverified email addresses for your instance, navigate to the Email, phone, username page in the Clerk Dashboard. Click on the settings icon next to "Email address" and uncheck the "Verify at sign-up" toggle.

Clerk initiates the email verification process at the outset. Upon successful email verification, regardless of the method, additional steps may be taken to validate existing connections or passwords. This is done to ensure the user's account remains secure.

Users with different email addresses

If a user has a different email from the one associated with the OAuth account, they can manually associate the two. To do so, they must:

1. Sign into their Clerk application with the account that uses their main email address.
2. In the Manage Profile section of the <UserProfile /> page, add the different email.

After following these steps, the user's OAuth accounts associated with both their primary and added email addresses will be linked to their main account.