> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runlayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Directory Sync Migrations

> Move users to a new email domain or a new directory and keep their Runlayer accounts, roles and history.

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.

> [!NOTE]
>
> Changing an email or a directory user ID needs Runlayer 4.2.0 or later and a Super Admin API key. See [Management API](https://docs.runlayer.com/platform-api.md#authentication). 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](https://docs.runlayer.com/platform-roles.md#changing-a-synced-users-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 account that holds the email | What sync does |
| - | - |
| Was never linked to the directory (the person signed in before directory sync was on, or is on the external allowed emails list) | Links it, if the account is active |
| Is linked to another directory user of the same directory, and your identity provider reports the same user ID for both | Links it, and reactivates it if it was deactivated (a rehire) |
| Is linked to another directory user of the same directory, and your identity provider reports a different user ID | Refuses the match |
| Is linked to a directory user of a previous directory connection (you reconnected or switched identity providers), or has no identity-provider user ID on record yet | Links it, if the account is active |
| Is linked to a directory user the directory still lists (full reconciliation only) | Refuses the match: two directory users share one address |

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**

```bash theme={null}
curl -X PATCH "https://<your-runlayer-host>/api/v1/users/<user_id>/identity" \
  -H "x-runlayer-api-key: <super-admin-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@new-company.com"}'
```

**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](#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:

```bash theme={null}
curl -X PATCH "https://<your-runlayer-host>/api/v1/users/<user_id>/identity" \
  -H "x-runlayer-api-key: <super-admin-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"reset_sign_in_binding": true}'
```

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](#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`.

```bash theme={null}
curl -G "https://<your-runlayer-host>/api/v1/admin/directory-sync/directory-users" \
  -H "x-runlayer-api-key: <super-admin-api-key>" \
  --data-urlencode "email=jane@new-company.com"
```

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

```bash theme={null}
curl -X PATCH "https://<your-runlayer-host>/api/v1/users/<user_id>/identity" \
  -H "x-runlayer-api-key: <super-admin-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@new-company.com", "workos_directory_user_id": "directory_user_01ABC..."}'
```

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**

Follow [Verify the result](#verify-the-result).

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

```bash theme={null}
curl -X PATCH "https://<your-runlayer-host>/api/v1/users/<duplicate_user_id>/identity" \
  -H "x-runlayer-api-key: <super-admin-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane+duplicate@new-company.com", "detach_directory_user": true}'
```

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](#verify-the-result).

## 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](https://docs.runlayer.com/platform-roles.md#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](https://docs.runlayer.com/platform-teams.md).

**6. Dry-run a full reconciliation**

```bash theme={null}
curl -X POST "https://<your-runlayer-host>/api/v1/admin/directory-sync/reconcile" \
  -H "x-runlayer-api-key: <super-admin-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}'
```

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**

Follow [Verify the result](#verify-the-result).

> [!WARNING]
>
> 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](https://docs.runlayer.com/platform-audit-logs.md).

## Troubleshooting

| What you see | Why | What to do |
| - | - | - |
| A second user exists under the new address | The directory provisioned the new address before the Runlayer account carried it, so nothing matched | Follow [A second account already holds the new address](#a-second-account-already-holds-the-new-address). Leave the original account active. Do not delete the second account. |
| The user was deactivated | Their directory user was removed, marked inactive, or missing at a full reconciliation | Make sure the directory lists them as active. Reactivate them on the **Users** page, then link the directory user straight away (Option 3) if sync does not. Revoked device keys and identity-provider links do not come back; the user sets them up again. |
| Sign-in fails with "This account's directory identity is unresolved" | Sync refused a match for that address, or a rebind that named a new directory user is waiting for reconciliation | Same person: name the directory user (Option 3), remove the old identity-provider account, then run **Reconcile data**. Different person: do not rebind; see [Changing a synced user's email or directory identity](https://docs.runlayer.com/platform-roles.md#changing-a-synced-users-email-or-directory-identity). |
| Sign-in fails with "This account is linked to a different identity at your identity provider" | The account is still bound to the sign-in identity the person used before | Reset the sign-in binding (Option 2). Naming a new directory user ID does this as part of the rebind. The reset is refused while the account is a refused directory match: reconcile first. |
| Sign-in fails with "User not provisioned via directory sync" | No account holds that address | Check that the directory lists the person under the address their Runlayer account has. |
| The email did not change after you edited it in your identity provider | Another Runlayer user, active or deactivated, holds the new address | Give that user a different address with the rebind request (reactivate them first if they are deactivated), then wait for the next sync. Deactivating them does not free the address. |
| The rebind request is refused | The response says why | See the list in [Changing a synced user's email or directory identity](https://docs.runlayer.com/platform-roles.md#changing-a-synced-users-email-or-directory-identity). |

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.