Introduction
TheMigrator is a Microsoft 365 tenant-to-tenant migration platform. IT teams and MSPs use it to move email, SharePoint, OneDrive, and Teams data between M365 tenants — with live progress monitoring, per-item error tracking, and delta sync to minimise cutover downtime.
All migrations run via the Microsoft Graph API using application permissions on an Azure App Registration. No data is ever stored permanently on TheMigrator servers — email streams directly between tenants and SharePoint files are staged briefly in Azure Blob Storage before being written to the destination.
Quick start
Get your first migration running in under 30 minutes.
Run a dry run before your first real migration. It validates all user mappings and estimates data volume without moving anything. A dry run on a 200-user tenant typically completes in 10–15 minutes.
Core concepts
Tenants
A tenant is a connected Microsoft 365 organisation. Each tenant has a role — source (where data comes from) or destination (where data goes to). You can connect any number of tenants to your TheMigrator organisation; a single tenant can be both source and destination across different jobs.
After connecting, TheMigrator runs a discovery scan to count mailboxes, sites, and users. Discovery is re-run automatically when you create a new job.
Jobs & workloads
A job is a single migration task — one workload type, between one source tenant and one destination tenant. To migrate email and SharePoint for the same pair of tenants, you create two separate jobs.
Status lifecycle
Every job moves through the following statuses:
Connecting tenants
OAuth consent flow
TheMigrator connects to M365 tenants using application permissions via OAuth 2.0 admin consent. A Global Admin on the target tenant must visit the consent URL and approve the requested Graph API permissions. This grants TheMigrator a long-lived access token that is stored encrypted.
- Go to Tenants → Connect tenant.
- Enter the tenant's primary domain (e.g. contoso.com) and select its role (source or destination).
- Click Connect — you will be shown an authorization URL.
- A Global Admin on that tenant must open the URL and click Accept.
- TheMigrator receives the OAuth callback and stores the encrypted token. Discovery begins automatically.
Admin consent must be granted by a Global Admin on the tenant. Users with lesser roles (e.g. Exchange Admin) cannot complete the consent flow for application permissions.
Custom App Registration
By default, TheMigrator uses its own shared Azure App Registration. For security-conscious customers or tenants with conditional access policies, you can bring your own App Registration.
- Create an App Registration in Azure Active Directory on the target tenant.
- Add the required Graph API application permissions (see table below).
- Grant admin consent for all permissions.
- Create a client secret (recommended expiry: 24 months).
- When connecting the tenant in TheMigrator, toggle 'Use own App Registration' and enter the Client ID and Client Secret.
See the Azure App Registration setup guide for a complete walkthrough.
Permissions by workload
The following Microsoft Graph API application permissions are required for each workload:
You can connect a tenant with only a subset of permissions and enable additional workloads later by updating the App Registration permissions and re-granting admin consent.
Migrations
Creating a job
Navigate to New migration in the dashboard. The wizard walks through six steps:
Scope options
Scope controls which data types are included in a migration job.
Sharing links (anonymous links and specific-people links) are not migrated for OneDrive or SharePoint. Users must recreate shared links in the destination tenant.
Storage & licensing checks
Before every migration launch, TheMigrator automatically runs pre-flight storage and licensing checks on the Review step. These checks compare source data sizes against destination quotas and flag issues that would cause the migration to fail or produce incomplete results — so you can fix them before data starts moving.
Checks appear as a green, amber, or red panel on the Review step. A red panel means one or more issues will cause data loss or job failure — resolve these before launching. Amber warnings are advisories that won't block the migration but may produce partial results.
Quota fields (sharepointQuotaBytes, sharepointUsedBytes, onedriveQuotaPerUserBytes) are populated during tenant discovery and returned in the GET /v1/tenants response. If they are absent, TheMigrator falls back to standard Microsoft defaults (50 GB / 1 TB).
Dry run mode
A dry run validates all user and site mappings, and estimates item counts and data volume, without moving any data. The job runs through the full discovery and mapping pipeline but stops before any write operations.
- Completes in 10–20 minutes for most tenants (no data transfer).
- Reports unmatched users or sites that need manual mapping.
- Estimates total item count and data volume for the actual run.
- Recommended for all tenants over 200 users or 1 TB of data.
- Enable via the toggle on the Schedule step, or via the dryRun field in the API.
Scheduling
Jobs can be started immediately or scheduled for a future time. For large tenants (500+ mailboxes or several TB of data), scheduling overnight avoids peak Graph API throttling during business hours.
- Select 'Schedule for later' on step 5 of the wizard.
- Choose a date and time in your local timezone.
- Scheduled jobs show as QUEUED until the start time, then transition to RUNNING.
- You can cancel a scheduled job at any time before it starts.
Batch scheduling
Batch scheduling splits a migration into multiple jobs — each covering a different subset of mailboxes, sites, or teams — that start at different times. It is designed for phased rollouts where you want to migrate a pilot group first, validate, then roll out to subsequent waves.
Enable batch scheduling on the Schedule & options step of the wizard. Two modes are available:
Each batch in Custom mode shows a searchable checkbox list of all available items. Items assigned to one batch are greyed out in all other batches. Click Add unassigned to instantly assign every item not yet allocated anywhere. Use the CSV button to paste a list of addresses or names — TheMigrator matches them by email address, display name, site name, or site URL and reports unmatched entries.
Any items not explicitly assigned to a batch are automatically added to the last batch at launch time. Use the assignment counter at the top of the Batches panel to confirm every item is covered before launching.
To create batch jobs via the API, use POST /v1/jobs/batch. Pass the same sourceTenantId, destTenantId, type, and scope for all batches, then specify per-batch scheduledAt, mailboxes, mailboxMappings, or siteMappings inside each batches[] item.
Maintenance mode
Administrators can enable maintenance mode from the Admin panel → System page. When active, a red banner appears at the top of every page — both the customer dashboard and the marketing/public pages — informing users that migrations are paused.
- Maintenance can be toggled on/off instantly from the admin System page.
- A schedule can be set (start and end time) — an amber banner appears before the window begins.
- Banners show without delay: the maintenance status is fetched fresh on every request with no caching.
- No customer action is required — all running jobs are automatically paused and resume when maintenance ends.
Monitoring
Job progress
The job detail view shows live progress for every running or completed job. Counters update in real time via Server-Sent Events — no page refresh needed.
Log stream
The log viewer streams structured log lines from the worker as they are emitted. Each line has a level and a message.
Throttle warnings (429 Too Many Requests from Graph API) are normal. The worker retries automatically with exponential backoff (1 s → 8 s → 64 s). Persistent 403 Forbidden errors usually indicate a missing Graph API permission.
The log stream is also available via the API as a Server-Sent Events endpoint. See the API reference → Stream job logs.
Exports
All job data can be exported for record-keeping or post-migration review:
Device agent
The MigratorAgent is a lightweight Windows service that runs on endpoints and lets you remotely trigger device migrations from the TheMigrator dashboard. It handles leaving the old domain and/or Azure AD tenant, clearing Office credential caches, and re-enrolling into the destination Entra ID and Intune — across a required reboot between phases.
The agent is an optional add-on for customers migrating Windows devices between tenants. It is not required for email, SharePoint, OneDrive, or Teams migrations.
Installation
Download MigratorAgent.exe from Settings → Devices in your dashboard, or directly from /downloads/MigratorAgent.exe. Run it once from an elevated command prompt to register the device and install the Windows service:
MigratorAgent.exe /install /org <orgId> /api https://api.themigrator.app
The installer registers the device with the API, saves a device secret to the Windows registry, and creates a Windows service (MigratorAgent) that starts automatically. The service checks in every 3 minutes for pending commands.
- Requires .NET 8 runtime — the exe is self-contained, no separate install needed.
- Must be run as Administrator (the service writes to HKLM).
- The orgId is shown on the Settings → Devices page and in the Devices API.
- To uninstall: MigratorAgent.exe /uninstall from an elevated prompt.
Commands
Commands are sent from the dashboard (Settings → Devices → select device → Send command) or via the API. The agent polls for commands every 3 minutes and executes them sequentially.
Device migration (FULL_MIGRATION)
FULL_MIGRATION is the primary command for moving a device from one tenant to another. It runs in two phases separated by a machine reboot.
The FULL_MIGRATION command payload accepts the following fields:
Generate a PPKG in the Intune portal: Devices → Enrollment → Windows → Bulk Enrollment Tokens → Create. The PPKG handles both Entra ID join and Intune enrollment in a single silent install — it is the most reliable enrollment method and is strongly recommended over enrollmentUrl.
The device will reboot 30 seconds after Phase 1 completes. Ensure all user work is saved before sending a FULL_MIGRATION command. The status shows RUNNING until Phase 2 completes after the reboot.
Security
For a full security overview, see the Security page. Enterprise customers can request a security questionnaire, penetration test results, and DPA from [email protected].
Billing
TheMigrator uses a seat-based model. A seat is consumed once per unique source object migrated (one mailbox = one seat, one OneDrive drive = one seat, one SharePoint site = one seat, one Team = one seat). Re-running delta syncs on an already-migrated object does not consume additional seats.
The 25 free seats on the Starter plan are permanent — no credit card required, no time limit. They are ideal for small migrations or for evaluating TheMigrator before committing to a plan.
Dry run jobs do not consume seats regardless of the number of items discovered. Only jobs that complete with status DONE or ERROR (i.e. data was moved) consume seats.
To upgrade your plan or discuss Enterprise pricing, visit Settings → Billing in your dashboard, or contact [email protected].