Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Migration API
Migration API is a REST-based interface that enables organizations to automate and streamline the migration of user environments, apps, and data into Windows 365 Cloud PCs. It provides a secure, scalable way to integrate migration workflows with existing tools and processes, reducing manual effort and minimizing downtime. By applying the API, IT teams can orchestrate bulk migrations, monitor progress, and ensure a consistent experience for end users—all while maintaining compliance and security standards.
This document provides technical requirements and step-by-step guidance for Microsoft partners and customers migrating Azure-based virtual machines (VMs) to Windows 365 Cloud PCs using the Microsoft Graph API. It's intended for engineering teams and IT administrators responsible for planning and executing migrations to Windows 365.
You’ll find detailed specifications for Virtual Hard Disk (VHD) preparation, API parameters, validation steps, and process diagram to ensure a smooth and secure migration experience. The document also outlines supported scenarios, current limitations, and best practices for snapshot-based provisioning. By following these guidelines, partners and customers can accelerate onboarding, minimize migration errors, and deliver a consistent Cloud PC experience for enterprise customers.
1. Supported Migration Scenarios
Migration from Azure-based virtual machines (Entra joined and Entra hybrid joined) to Windows 365 Cloud PCs.
Only VHD snapshot-based provisioning is supported; image-based imports aren't available.
2. VHD Format and Storage Requirements
VHD Format
| Requirement | Details |
|---|---|
| Format | Fixed-format VHD only (no Virtual Hard Disk v2 (VHDX) or dynamic disks) |
| Generation | Gen2 VMs only |
| OS Disk | Windows 10 or later; no data disks |
| VM State | VM must be stopped (deallocated) before snapshot |
| VM Agent | Healthy Azure VM agent required |
| 3rd-party Agents | Must be uninstalled before snapshot creation |
Storage
Store the VM snapshot as a page blob in a customer-owned Azure Storage account.
Access via SAS URI (recommended) or assign required permissions to the Windows 365 service using managed identity.
Cross-tenant access isn't supported.
3. API Parameters and Provisioning Flow
Required API Parameters
| Parameter | Description |
|---|---|
| userId | Entra ID of the target user |
| snapshotLocation | SAS URI or storage account details |
| policyId (optional) | Used to determine provisioning policy |
Ensure the user is Entra ID joined and doesn't already have the same version of Cloud PC.
Assign the appropriate license to the user after the snapshot is uploaded to trigger provisioning.
4. Validation Requirements (Checklist)
Before initiating migration, ensure the following validation checks are met:
| # | Validation check | Purpose |
|---|---|---|
| 1 | VHD bootability | Validate that the VM is bootable and has a healthy Azure VM agent |
| 2 | Gen2 format | Only Gen2 VMs are supported |
| 3 | OS version compatibility | Must be supported by Windows 365 |
| 4 | No 3rd-party agents | 3rd-party agents not supported |
| 5 | No data disk | Only OS disk supported |
| 6 | Azure VM agent health | Must be healthy and responsive |
| 7 | Disk size compatibility | Must fit within assigned license |
| 8 | CSE readiness | Ensure network compatibility |
| 9 | Snapshot-user match | Prevent cross-user provisioning |
| 10 | File integrity | Ensure no corruption |
| 11 | File format | Fixed-format VHD only (no Virtual Hard Disk v2 (VHDX) or dynamic disks). |
| 12 | Windows OS | Must be Windows 10+ |
Monitor provisioning status and error messages via the Graph API.
5. Migration Flow Diagram
6. Snapshot-Based Provisioning
Enforced via Graph API only (not Intune).
Admins must flag users for snapshot-based provisioning via user settings; partners must implement that feature.
Once provisioned, users can be removed from the snapshot group to allow image-based reprovisioning.
7. Limitations
Only Enterprise Cloud PCs are supported.
Only Commercial cloud is supported initially; Gov cloud and GPU may be enabled in future phases.
No reuse of snapshots across multiple provisions.
One user can only have one imported VHD in Windows 365 at a time; a new VHD can be imported only after the current one is used or deleted.
No support for Intune UX—partners must build their own tooling.
No support for third-party agents—must be uninstalled prior to snapshot creation.