# Email Changes ## Introduction When a user's email address changes at their Identity Provider (IdP), AuthKit can propagate that change to the [User object](https://workos.com/docs/reference/authkit/user) so it stays in sync with the authoritative source. A user is **domain-managed** when their email domain matches one of the [organization's verified domains](https://workos.com/docs/authkit/domain-verification). For enterprise identity sources (Directory Sync and SSO), an email change propagates only when the identity source has **user-level authority** over the AuthKit user. An identity source has user-level authority when the user's **current** email domain is managed by the organization's [domain policy](https://workos.com/docs/authkit/organization-policies/domain-policy)—that is, the domain is [verified](https://workos.com/docs/authkit/domain-verification) and has domain capture enabled for the organization that owns the directory or SSO connection. In addition, the **new** email asserted by the identity source must be on one of the [organization's verified domains](https://workos.com/docs/authkit/domain-verification). The authority check is evaluated against the user's current email, not the new one. This prevents an identity provider from taking over a domain guest—such as a user with a personal email address who was invited to the organization—by asserting a new email on the organization's domain. Social login (OAuth) follows separate rules, described in the [precedence rules](#precedence-rules) below. ## Native email changes Users who aren't managed by an enterprise identity source—such as those who sign in with a password or social login—can change their own email address directly, without an IdP involved. The [User Profile widget](https://workos.com/docs/widgets/user-profile) lets users update their email from your application's UI, sending a verification code to the new address to confirm ownership. To build your own flow, use the [send email change](https://workos.com/docs/reference/authkit/user/send-email-change) endpoint to send the code, then the [confirm email change](https://workos.com/docs/reference/authkit/user/confirm-email-change) endpoint to apply the change once the user enters it. Enterprise-managed users (linked to a directory or SSO connection) can't change their email this way—the [update user](https://workos.com/docs/reference/authkit/user/update) API also rejects email changes for them, because their identity provider is the authoritative source. Those changes propagate automatically according to the rules below. ## Precedence rules When multiple identity sources are linked to the same AuthKit user, the following determines which source can update the email: | Source | Can update email? | Condition | | --- | --- | --- | | Directory Sync | Yes | Directory has user-level authority over the user, and the new email is on one of the organization's verified domains | | Enterprise SSO (SAML/OIDC) | Yes | SSO connection has user-level authority over the user, the new email is on one of the organization's verified domains, and the user is not directory-managed | | Social login (OAuth) | Yes | User has no enterprise SSO profile or directory user linked (on the user or any of their organization memberships), only one OAuth profile is linked, and the OAuth provider reports the email as verified | Directory Sync takes precedence over SSO. If a user has both a directory user and an SSO profile linked, only the directory can update the email; an SSO login will not overwrite a directory-sourced email. When an identity source lacks user-level authority, the email change is skipped but other attribute updates (such as the user's name) still apply. A directory user without user-level authority stays linked at the organization membership level only; it is not linked to the AuthKit user itself. ## Collision handling If the new email address already belongs to another AuthKit user in the same environment, the email change is **skipped**. The AuthKit user retains its current email and all other attribute updates (name, etc.) still apply. This prevents unintended account merging when two users at the same IdP happen to swap or share email addresses. ## Directory ownership For domain-managed users, the first directory to link to a user owns that user, and a second directory can only take ownership if its organization has [domain capture](https://workos.com/docs/authkit/organization-policies/domain-policy) enabled for the email domain. See [directory provisioning](https://workos.com/docs/authkit/directory-provisioning) for the full ownership rules. ## Side effects of email changes When an email change takes effect—whether propagated from an identity provider or made natively through AuthKit: - **OAuth profiles are unlinked**: Any linked OAuth identity (Google, GitHub, etc.) whose email no longer matches is removed, since it was verified against the old email - **Sessions remain active**: Existing sessions are not revoked by an email change alone - **Email verification**: An email change from a trusted enterprise source (directory, or SSO with a verified domain), or one a user confirms with a verification code, is marked as verified. An email set directly through the [update user](https://workos.com/docs/reference/authkit/user/update) API is not automatically verified. ## Frequently asked questions ### How do email changes interact with identity linking? Email changes are applied after [identity linking](https://workos.com/docs/authkit/identity-linking). First, the correct AuthKit user is identified—via an existing link, the identity provider's unique user identifier, or an email match. Then, if the source's email differs from the AuthKit user's email, the precedence rules determine whether to update it. Because enterprise users are linked on the identity provider's unique user identifier rather than the email address, an email change on the directory or SSO side resolves to the same user instead of creating a duplicate. See [identity linking](https://workos.com/docs/authkit/identity-linking) for the full resolution order.