# Unique Emails and External IDs ## Introduction Directory Sync requires two values on a directory user to be unique within a directory in addition to username: the email address, and the external ID that the identity provider assigns to a person. If an identity provider tries to provision or update a directory user with a value that another user in the same directory already has, that request is declined and the affected user won't sync until the conflict is resolved. ### Why uniqueness matters Unique emails make user resolution predictable. When each active user in a directory has a distinct email, just-in-time provisioning and your own application can reliably resolve a person by their email address. This keeps downstream authentication and account-linking behavior consistent for your users. Unique external IDs keep that resolution durable. An external ID is meant to be the identifier the identity provider generates for a person, so it stays the same when their name, username, or email changes. When two users share one, the same person exists twice in the directory and your application can no longer tell which record to trust. *** ## Best practices for IT Admins Conflicts originate in your customers' identity providers, so the fixes are IT admin actions. Share this guidance with the affected admins to keep directories syncing cleanly. - **Keep the username a stable field.** WorkOS identifies a directory user by their SCIM username. When a person's username changes, most providers re-provision them to WorkOS as a brand-new user instead of updating the existing one. To avoid this, map userName to a value that doesn't change for a person rather than something mutable; don't re-point the username mapping on a live directory; and don't rename users while you're also moving them between synced groups or reassigning them. - **Genuinely distinct identities need distinct emails.** Give each person their own email address. For service or secondary accounts that don't need to sync, exclude them from the provisioning application instead of sharing emails. - **Let the identity provider own the external ID.** External IDs should be stable and unique for each user, ideally the object ID generated by the identity provider. - **Avoid duplicate applications.** Ensure there is only one application in the identity provider pointing to the WorkOS directory. If there are multiple, reset the directory and use a fresh application. - **On rehire, reactivate the original user record.** Reactivating an account allows the user to keep their access and avoids creating duplicates. If a fresh account is required, delete the old one in the identity provider before provisioning a new one.