Migrate Sophos devices between Central tenants

During a company acquisition, tenant consolidation or correction of an incorrect customer assignment, managed computers are moved from a sending Sophos Fusion account to a receiving one with Device Migration. The standard process uses the Endpoint API: first create a Receiving Job in the target, then start the corresponding Sending Job in the source account.

Scope: The current Sophos help describes this process for “computers”. Before rollout, confirm which operating systems, device types, agent versions and installed products are eligible in the specific tenant by checking the current Endpoint API documentation, the live tenant’s response or with Sophos Support. The general Endpoint API types are not a migration allowlist. Access points and switches have their own procedures and are not part of this API workflow.

What Device Migration does – and what must be prepared separately

Device Migration changes the computer’s registration and managing account. Following a successful migration, it is managed by the receiving account. If the migration fails, Sophos states that it remains managed by the sending account.

The public documentation does not describe the transfer of policies, groups, global exclusions, website lists, licences, product assignments, alerts, investigations or audit history. It therefore cannot be inferred either that these data are transferred automatically or that they remain in their entirety in the source account. Prepare the target configuration and verify the effective state after migration.

Plan prerequisites and a pilot

Before the first job, inventory the source and target and define a small, representative pilot. Put critical servers, VDI systems, home-working devices, isolated computers and rarely connected laptops into separate waves.

The following prerequisites must be met:

• The person carrying out the migration has the Sophos Admin role in both accounts.
• Separate API credentials with the Service Principal Super Admin credential role exist for both accounts. A human Super Admin must create and manage these credentials; the Admin role alone is not sufficient.
• The tenant ID and regional API host are known for both accounts. Determine them through the standard Sophos API setup rather than guessing them.
• The endpoint IDs to be migrated come from the sending account, and the eligibility of every pilot device has been confirmed in the live tenant or with Sophos Support.
• Suitable licences, policies, groups, exclusions and website lists are prepared in the target.
• The target account’s Update Caches, Message Relays and proxies are reachable from each device location.
• Isolations, open alerts and active investigations are documented; preserve any required incident and audit evidence before the move.

An API client secret and the bearer token obtained from it each belong to one account. The Migration Job Access Token subsequently issued by the Receiving Job is a different secret. Client secrets, bearer tokens and Migration Job Access Tokens must not appear in screenshots, tickets, shell history or operational logs.

Allow Device Migration in both accounts

First sign in to the sending account and then the receiving account, opening Global Settings > Platform > Device Migration in each:

1. Turn on Allow device migration.
2. Set the shortest time limit sufficient for the pilot or wave.
3. Immediately before starting the jobs, check again that the window is active in both accounts.

If the option is locked, the setting comes from the partner’s or enterprise administrator’s global settings. Do not attempt to circumvent this with workarounds; the responsible higher-level administrator must grant approval.

Perform the migration with a Receiving Job and Sending Job

The current Sophos help for Device Migration describes the job sequence. The Endpoint Migration API Guide leads to the current API reference. Check the exact request structure, field values and current quantity limit directly in the current Endpoint API definition immediately before execution. Do not adopt historical payloads or limits without checking them. Use the following sequence:

1. Create the Receiving Job in the target

The operation pattern is POST /endpoint/v1/migrations. The request uses the regional API host and credentials of the receiving account. It sends the bearer token in the Authorization header, the receiving account’s ID in the X-Tenant-ID header and, when using a JSON body, the Content-Type: application/json header.

The body identifies the sending account and the confirmed devices in the pilot or wave. In the historical schema, these fields are named fromTenant and endpoints; confirm before the run whether they still have exactly these names in the live schema and whether both are required in this step.

Save the following from the response:

• the Receiving Job ID;
• the Migration Job Access Token for the corresponding Sending Job;
• an expiry date issued by the current API, if present.

The job ID may be included in the change log. Pass the Migration Job Access Token only through a protected secret channel to the person or automation that creates the Sending Job, and do not log it permanently.

2. Start the Sending Job in the source

Next, authenticate separately with the sending account. The operation pattern is PUT /endpoint/v1/migrations/{receivingMigrationJobId}. The path contains the Receiving Job ID. The request sends the bearer token in the Authorization header and the sending account’s ID in the X-Tenant-ID header; add Content-Type: application/json when using a JSON body.

The Sending Job uses:

• the confirmed list of endpoint IDs from the source account;
• the ID of the previously created Receiving Job;
• its Migration Job Access Token.

The historical schema calls the body fields token and endpoints. Confirm these names and the current response structure in the live definition before the run as well.

The Sending Job starts the migration. Before submitting it, check the tenant context, endpoint list and wave size again. Do not reuse a token or job ID from another run. Record the Sending Job ID returned by the current API together with the Receiving Job ID; record an expiry date only if the live response provides one.

3. Monitor status and queue

Query progress with GET /endpoint/v1/migrations/{migrationJobId}/endpoints. Make the request for each relevant Sending and Receiving Job in the context of the sending or receiving account respectively, using that account’s bearer token and X-Tenant-ID. If results span multiple pages, query every page and reconcile them against every requested endpoint ID. Optionally, GET /endpoint/v1/settings/migration shows whether migration is allowed in the relevant account.

The current live definition determines the status values and detail fields. The historical API schema used pending, succeeded and failed; depending on the result, it also returned a new endpoint ID, timestamps and a failure reason, among other details. These names are guidance, not a guarantee of the current schema. Preserve the values and fields actually returned.

Computers remain in the migration queue for up to 14 days. An offline computer must come online within this period. A shorter configured migration window may further restrict the available period. If the device remains offline for longer and the migration expires, it fails and an administrator must manually queue it for migration again.

Do not pre-emptively uninstall a pending offline device or modify it with local tenant ID changes. First restore connectivity within the valid window. After a failed attempt, the device remains managed by the source account.

Verify success in the source, target and on the device

An API status alone is not complete acceptance evidence. Before the next wave, reconcile the results across both accounts and the computer.

Official migration evidence

1. The sending account’s Audit Log contains the Send endpoints to another tenant event.
2. The successfully migrated computer’s event states Device registered with new account . It’s now managed by that account.
3. For a failed computer, it instead states Device failed to register with new account . It continues to be managed by this account.
4. The receiving account’s Audit Log contains Allow endpoints to migrate to this tenant.
5. In the target, under My Environment > Computers & Servers, the computer is registered, assigned to a user and up to date.
6. Every requested endpoint ID is reconciled against the API results; also document the new endpoint ID if one is returned.

Operational acceptance

Then verify that the computer is actually protected and operated as intended in the target:

• Device type, licence and installed products match the intended target configuration.
• Target group, effective policies, global exclusions and website lists are correct.
• Agent updates, an approved protection test and the intended response functions work.
• Update Cache, Message Relay and proxy behaviour match the target account.
• The old record in the source account is not confused with the active target registration.

Only begin the next small wave when the API result, audit and endpoint events, and operational acceptance all agree.

Narrow down failures safely

Job remains open

If the current API shows a state that is not yet complete, first check whether the computer is online, can reach Sophos and both migration windows are still valid. While migration remains allowed, an offline device may remain in the queue. After failure or expiry, manually queue the endpoint again with a new, valid migration window.

Migration fails

First reconcile any failure reason returned by the current API with the computer’s event and the Audit Logs of both accounts. Then check the tenant context, endpoint ID, job association, current migration approval and the confirmed eligibility of that computer. If the failure is unclear, preserve both job IDs, the endpoint ID, timestamps, API correlation data and an SDU archive, then provide them to Sophos Support – without secrets or tokens.

A failure means management was not transferred successfully; the device remains with the source account. For an already successful migration, the documented API provides no established automatic cancel, undo or rollback process. Plan a move back as a new, separately confirmed migration or re-registration.

API request is rejected

Check whether the bearer token, X-Tenant-ID and regional API host belong to the same account and whether the API credentials there have the Service Principal Super Admin role. Do not confuse the bearer token with the Receiving Job’s Migration Job Access Token. Allow device migration must also still be active in both accounts.

Windows alternative: re-register with --registeronly

--registeronly is not part of the Receiving and Sending Job process and does not replace API migration. The switch is used for the separate Windows re-registration of an already protected device when Device Migration is not suitable or available for the specific case and this method has been confirmed against the current Windows installer documentation or by Sophos Support.

It has its own prerequisites:

• A functioning Sophos Protection installation is present on the Windows device.
• A current, unmodified SophosSetup.exe installer has been obtained from the target account under My Environment > Installers.
• In accordance with the documented prerequisite for --registeronly, Tamper Protection is turned off on the device.
• The command runs locally or through software distribution with administrator rights; the device must be able to reach Sophos.

On the Windows device, open Command Prompt or PowerShell as administrator and start the target installer:

.\SophosSetup.exe --registeronly

The filename and path may differ. A package from the source account would not achieve the intended target. After the command, perform the same operational target checks described above; the installer process finishing is not evidence of success on its own.

Do not apply the Windows switch to macOS or Linux. To re-register other platforms, use the current platform procedure documented by Sophos or contact Sophos Support. If the existing Windows agent is damaged or has already been removed, --registeronly cannot be used. Follow the supported repair or uninstall procedure, then reinstall with the target installer. For Windows, Uninstall Sophos Endpoint with Tamper Protection enabled describes the supported recovery procedure.

Registry changes, Safe Mode tricks, modifications to MCS files and manually configured tenant IDs are not supported procedures for a migration or a return to the source account. If --registeronly fails, check the installer’s origin and currency, administrator rights, internet/proxy connectivity and agent health. Preserve installation logs and, if required, an SDU archive before involving Sophos Support.

Complete the wave and preserve evidence

After each wave, reconcile the intended list with the results. Document:

• the Receiving and Sending Job IDs and the job association shown in the API result;
• the old and, if returned, new endpoint ID;
• the status, time and failure details returned by the current API;
• the approved migration window, wave size and responsible person;
• technical and operational acceptance;
• the owner of the API credentials used, but no secrets, bearer tokens or Migration Job Access Tokens.

After the final wave, turn off Allow device migration or close the time-limited approvals, remove temporary exclusions and return all protection controls to their intended state. Do not delete old source objects indiscriminately: first check the API result, ownership status and retention requirements. Continue to archive incident and audit evidence separately in accordance with internal requirements.

Frequently asked questions