Skip to main content
This guide covers two changes to a workspace that uses directory sync:
  • Email domain change: people keep working, but their addresses move (for example jane@old-company.com becomes jane@new-company.com).
  • Directory move: you reconnect directory sync or switch identity providers (for example Entra to Okta).
In both cases the goal is the same: each person has the same Runlayer user ID before and after, so their roles, teams, agents, skills, plugins and history stay with them.
Changing an email or a directory user ID needs Runlayer 4.2.0 or later and a Super Admin API key. See Management API. Releasing a duplicate account’s directory user, resetting a sign-in binding, and reading directory identity from the API need a release after 6.2.0. On 6.2.0 or earlier, contact Runlayer support before those steps. The requests are in Changing a synced user’s email or directory identity.

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.
For each user the directory lists, Runlayer looks for an existing account in this order:
  1. By directory user ID. The account already linked to that directory user is updated in place, including its email address.
  2. 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).
  3. No match. Runlayer creates a new user.
The identity provider’s user ID is the identifier your identity provider assigns to the account itself. It stays the same when the email changes and is new when the account is deleted and re-created. Runlayer records it the first time a user syncs on 4.2.0 or later. When sync refuses a match it leaves the account as it is and skips the directory user. It does not create a second user. If the account is active, nobody new can attach to it by email at sign-in until the conflict is resolved. People who have already signed in to that account are not affected. When a directory user goes away (removed, marked inactive, or missing at a full reconciliation), Runlayer deactivates the linked account and revokes its device keys and identity-provider links. Reactivating the account later does not bring those back. This is why the order of the steps below matters.

Before you start

  • Record each user’s Runlayer user ID. It is your acceptance test. List users with GET /api/v1/users/?include_inactive=true and keep id, email and is_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.
1

Allow the new address, if needed

If the person’s current address is on the external allowed emails list (Settings → Sign-in & provisioning), add the new address to the list. Otherwise Runlayer refuses the next step.
2

Set the new email on the existing account

3

Assign the user to Runlayer in your identity provider

Assign them under the new address. Within about 10 minutes sync links the directory user to the existing account by email.
4

Verify

Follow Verify the result. Sync keeps the account’s previous sign-in identity when it links by email. If the person now signs in with a new identity-provider account and sign-in fails with “This account is linked to a different identity at your identity provider”, reset the sign-in binding and try again:
The reset is refused while sync has marked the account as a refused directory match. Remove the other directory user under that address, run Reconcile data, then send the reset again.

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.
1

Look up the new directory user

After the new identity-provider account exists, read the directory user for the new address. Use id as workos_directory_user_id. linked_user_id is the Runlayer user that already holds it, or null.
2

Bind the new email and the new directory user together

Send both in one request, before sync creates a second user. Naming the new directory user drops the previous sign-in binding and blocks first-time sign-in by email until a full reconciliation sees only one directory user under the address.
If sync already linked this account to the new directory user and sign-in is still refused, the directory user is already right. Reset the sign-in binding as in Option 2 instead of sending the directory user ID again.
3

Remove the old identity-provider account

Unassign or delete it only now. Before the previous step this deactivates the user and revokes their device keys.
4

Run Reconcile data

Once the directory lists one user for the address, reconciliation lifts the sign-in block from the previous step.
5

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 409 IdentityAlreadyBound. If that happens, start again from the deactivation.
1

Deactivate the second account

Deactivate it on the Users page. If it has already been signed in to, deactivation suspends its API keys, delegations and grants. Those do not move to the original account. Leave this account deactivated afterwards.
2

Release its directory user and address

Read 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.
Check that the account is still deactivated. Sync reactivates a deactivated account while the directory still lists its directory user as active, so a delay here can turn it back on.
3

Rebind the original account

Send the new email and the directory user ID you just released, in one request, as in Option 3. Then remove the old identity-provider account, run Reconcile data, and verify.

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.
1

Keep a Super Admin who does not depend on the directory

Pin a manual Super Admin role on the admin who runs the move. Directory sync preserves a pinned manual role; every other role follows the new directory’s role assignment. See SCIM Role Sync.
2

Line up the new directory

In the new identity provider, assign everyone who should keep access, under the same email address their Runlayer account holds. Reactivate any deactivated Runlayer user who should come back: sync does not link deactivated accounts after a directory move.
3

Disconnect the old directory

Do this shortly after 00:00 or 12:00 UTC, from Settings → Sign-in & provisioning → Manage Directory Sync. If the portal does not offer it for your provider, Runlayer support disconnects it for you. While no directory is connected nobody is deactivated and existing users keep signing in. Anyone who can pass your single sign-on gets an account on first sign-in, as in a workspace without directory sync.
4

Connect the new directory

Set up role assignment for it, then wait for your identity provider to finish its first push of users and groups.
5

Move teams and policies to the new groups

Groups do not carry over. The new directory’s groups arrive as new groups, even when the names match, and the next full reconciliation removes the old directory’s groups or leaves them granting nothing. Before that reconciliation, bind teams to the new groups and update any policy that names a group. See Teams.
6

Dry-run a full reconciliation

A dry run changes nothing and reports what a real run would do, for example 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.
7

Run Reconcile data

Run it for real once the dry run is clean, or let the next scheduled reconciliation do it.
8

Verify

If email addresses change in the same move, set the new email on each account (the request in Option 2) after you disconnect the old directory and before you connect the new one. If people will also sign in with different identity-provider accounts than before, reset the sign-in binding after the new directory has linked the account, as in Option 2.

Verify the result

Check each migrated user, starting with your pilot:
  • Same user ID. GET /api/v1/users/?include_inactive=true shows 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_rebound with 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.