Email Changes
How email address changes from identity providers propagate to AuthKit users.
When a user’s email address changes at their Identity Provider (IdP), AuthKit can propagate that change to the User object 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. For enterprise identity sources (Directory Sync and SSO), email changes propagate only to domain-managed users. Social login (OAuth) follows separate rules, described in the precedence rules below.
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 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 endpoint to send the code, then the 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 API also rejects email changes for them, because their identity provider is the authoritative source. Those changes propagate automatically according to the rules below.
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 | User is domain-managed |
| Enterprise SSO (SAML/OIDC) | Yes | User is domain-managed, organization has verified domain, and user is not directory-managed |
| Social login (OAuth) | Yes | User has no enterprise SSO profile or directory user linked |
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.
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.
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 enabled for the email domain. See directory provisioning for the full ownership rules.
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 API is not automatically verified.
How do email changes interact with identity linking?
Email changes are applied after identity linking. First, the correct AuthKit user is identified (via existing link or email match). Then, if the source’s email differs from the AuthKit user’s email, the precedence rules determine whether to update it.