- Email domain change: people keep working, but their addresses move (for example
jane@old-company.combecomesjane@new-company.com). - Directory move: you reconnect directory sync or switch identity providers (for example Entra to Okta).
How Runlayer matches directory users
Directory sync runs in two ways, and both apply the same rule:- Events, about every 10 minutes: changes your identity provider pushes (a user created, updated or removed).
- Full reconciliation, every 12 hours at 00:00 and 12:00 UTC, or on demand with Reconcile data under Settings → Sign-in & provisioning: Runlayer reads the whole directory and corrects any drift.
- By directory user ID. The account already linked to that directory user is updated in place, including its email address.
- By email, within your workspace. The account is linked to the directory user only when Runlayer can tell it is the same person (see the table below).
- No match. Runlayer creates a new user.
Before you start
- Record each user’s Runlayer user ID. It is your acceptance test. List users with
GET /api/v1/users/?include_inactive=trueand keepid,emailandis_active. - Check the destination addresses are free. No other Runlayer user, active or deactivated, may already hold an address you are moving someone to. Runlayer never merges two users. Deactivating the other user does not free the address; move them to a different one.
- Deactivate people who have left before the change. An active account whose address is later given to someone else can be matched to that person.
- Pilot one user end to end, including a fresh sign-in, before you move everyone else.
- Plan around the full reconciliation. There is no switch that pauses directory sync. You control the order with what you assign in your identity provider and when. Start a change shortly after 00:00 or 12:00 UTC so the next scheduled reconciliation is as far away as possible.
Change the email domain
Pick the option that matches how your identity provider makes the change.Option 1: Change the address on the existing identity-provider account
This is the recommended path and needs nothing in Runlayer. The directory user stays the same, so sync finds the account by its directory user ID and updates the email within about 10 minutes. If another Runlayer user already holds the new address, sync keeps the old address on the account and updates everything else. Check the user’s email afterwards.Option 2: The account is not linked to the directory yet
Use this when the person signed in before directory sync was on, or through the external allowed emails list, and your identity provider will now provision them under the new address. If the directory provisions the new address first, nothing matches and sync creates a second user, so set the email in Runlayer first.Allow the new address, if needed
Set the new email on the existing account
Assign the user to Runlayer in your identity provider
Verify
Option 3: New identity-provider accounts for people already linked to the directory
Avoid this path if you can use Option 1. Runlayer cannot tell that a new identity-provider account belongs to the same person. While the account is still linked to the old directory user, sync writes that user’s address back over an email you set on its own. Removing the old account first deactivates the Runlayer user. Move one user at a time, and finish the rebind in one sitting, at least 30 minutes away from 00:00 and 12:00 UTC. If assigning the new account already created a second Runlayer user, use A second account already holds the new address instead.Look up the new directory user
id as workos_directory_user_id. linked_user_id is the Runlayer user that already holds it, or null.Bind the new email and the new directory user together
Remove the old identity-provider account
Run Reconcile data
Verify
A second account already holds the new address
The directory provisioned the new address before the existing account carried it, so sync created a second user. That second user holds the directory user ID and the address. Runlayer does not merge users. What was created on the second account stays there. Do not delete the second account. Deactivate it, release its directory user, then rebind the original. Do it straight through, and do not run Reconcile data between the detach and the rebind: a sync for the released directory user creates a fresh account, and the rebind then returns 409IdentityAlreadyBound. If that happens, start again from the deactivation.
Deactivate the second account
Release its directory user and address
workos_directory_user_id from the second account first (GET /api/v1/users/<duplicate_user_id>/identity). You send that ID to the original account in the next step.Rebind the original account
Move to a new directory
Use this when you reconnect directory sync or switch identity providers and people keep their email addresses. Runlayer links each user in the new directory to the existing active account with the same email. At the next full reconciliation it deactivates every linked account the new directory does not list.Keep a Super Admin who does not depend on the directory
Line up the new directory
Disconnect the old directory
Connect the new directory
Move teams and policies to the new groups
Dry-run a full reconciliation
users +0 created, 212 updated, 0 deactivated. The deactivated count must match the people you expect to lose access. In a like-for-like move that is zero. If it is higher, someone is missing from the new directory or listed under a different address. Fix that in your identity provider and run the dry run again.Run Reconcile data
Verify
Verify the result
Check each migrated user, starting with your pilot:- Same user ID.
GET /api/v1/users/?include_inactive=trueshows the ID you recorded, now with the new email, and no second user under the old or new address. - Active, with the roles, groups and teams you expect.
- Fresh sign-in. The person signs out, signs in again through single sign-on, and sees their own agents, skills and history.
- Audit log. Each rebind appears as
user_identity_reboundwith the previous and new values. See Audit Logs.
Troubleshooting
What is not supported
- Merging two users. A second account is released and the original is rebound, as above. Anything created on the second account stays there.
- Bulk ownership transfer as a migration tool. It is not available, and moving ownership would not move a person’s credentials, delegations or connector grants.
- Direct database edits, including on self-hosted deployments. They skip the checks and the audit trail the rebind API applies.