Overview of Microsoft Entra Backup and Recovery APIs

Namespace: microsoft.graph.entraRecoveryServices

The Microsoft Entra Backup and Recovery APIs in Microsoft Graph enable you to programmatically back up and restore critical directory objects to a previously known good state. These APIs help IT administrators recover from accidental changes or security compromises by viewing available backups, previewing restoration changes, executing recovery operations, and monitoring job progress.

Supported directory objects

The backup and recovery APIs support the following Microsoft Entra directory objects. For each object type, only a subset of properties and relationships are tracked and supported in the backup and recovery process.

• Users
• Groups - Microsoft 365 and security groups
• Applications
• Service principals
• Conditional Access policies
• Named location policies
• Authentication method policies
• Authorization policies
• OAuth2 permission grants
• App role assignments

Agent identities associated with users, applications, or service principals are also supported.

For more information, see Supported objects and recoverable properties in Microsoft Entra Backup and Recovery.

Key API concepts

Snapshots

A snapshot represents a point-in-time backup of the tenant's directory data. Each snapshot has a unique identifier (base64-encoded timestamp) and tracks the total count of changed objects. Use snapshots as the starting point for both preview and recovery operations.

Microsoft Entra automatically creates one backup snapshot per day and retains up to five days of snapshot history. Snapshots are non-editable and can't be deleted or disabled by any user or application.

Jobs

The backup and recovery process revolves around two types of jobs: preview jobs and recovery jobs, represented by the recoveryPreviewJob and recoveryJob resource types, respectively.

You can scope both preview and recovery jobs to specific subsets of data using filtering criteria: — Limit the scope to specific entity types (for example, only users, or only users and groups). — Limit the scope to specific objects identified by entity type and object ID.

Jobs are long-running operations. When you create a job, the response includes a Location header with the URL of the created job resource. Poll this resource to check the job status until it completes.

• A successful preview job provides a comprehensive list of objects that would be affected by a recovery operation, along with the specific property changes.
• A successful recovery job applies the necessary changes to restore the tenant's directory objects to the snapshot state. After completion, you can review any failed changes that couldn't be applied.

Only one job (preview or recovery) can run at a time per tenant. Wait for a running job to complete or cancel it before starting a new one.

Recovery preview jobs

A recoveryPreviewJob is a "dry run" that calculates the differences between the current tenant state and a selected snapshot. Preview jobs don't modify any data.

A preview job can be successfully completed, failed, or abandoned (canceled).

• After a preview job completes, call the getChanges function to enumerate the objects that would be affected, along with the specific property changes.
• If a preview job fails, call the getFailedChanges function to review the error details and understand the failure reason.
• To cancel a preview job, call the cancel function. No results are available for an abandoned job.

Each changed object returned by getChanges or getFailedChanges includes a recoveryAction property indicating what the recovery operation does to that object:

Recovery jobs

Unlike a preview job, a recoveryJob executes the actual restoration of directory objects to the selected snapshot state. After a recovery job completes, call the getFailedChanges function to review any changes that couldn't be applied.

Typical workflow

The following diagram illustrates the typical end-to-end workflow for using the backup and recovery APIs:

Step 1: List available snapshots
Retrieve the available backups to identify the snapshot you want to restore to.

GET /directory/recovery/snapshots

Step 2: Create a preview job
Create a preview job to calculate the differences between the current tenant state and the selected snapshot. Optionally, include filtering criteria to limit the scope.

POST /directory/recovery/snapshots/{snapshot-id}/recoveryPreviewJobs

Step 3: Poll the preview job status
The preview job is a long-running operation that returns a 202 Accepted response with a Location header that points to the created job resource. Poll its status until it completes. When the job completes (successful, failed, or abandoned status), retrieve the results.

GET /directory/recovery/snapshots/{snapshot-id}/recoveryPreviewJobs/{job-id}

Step 4: Review the changes
After the preview job completes successfully, retrieve the list of objects that would be affected.

GET /directory/recovery/snapshots/{snapshot-id}/recoveryPreviewJobs/{job-id}/getChanges

Step 5: Create a recovery job
After reviewing the preview, create a recovery job to apply the changes. You can use the same filtering criteria as the preview.

POST /directory/recovery/snapshots/{snapshot-id}/recoveryJobs

Step 6: Monitor the recovery job
The recovery job is a long-running operation that returns a 202 Accepted response with a Location header that points to the created job resource. Poll its status to track progress, including the number of objects and links modified. When the job completes (successful, failed, or abandoned status), retrieve the results.

GET /directory/recovery/snapshots/{snapshot-id}/recoveryJobs/{job-id}

Step 7: Review failed changes (if any)
If the recovery job reports failed changes, retrieve the details to understand what couldn't be applied and why.

GET /directory/recovery/snapshots/{snapshot-id}/recoveryJobs/{job-id}/getFailedChanges

Audit logs

All operations performed through the backup and recovery APIs are logged in the Microsoft Entra audit logs with the category "Backup and Recovery". You can use these logs to track when snapshots were created, when preview and recovery jobs were initiated, and their outcomes.

Permissions and privileges

The backup and recovery APIs support both delegated and application permissions. For more information about permissions required to call these APIs, see the individual API reference topics for each operation.

In addition to Microsoft Graph permissions, the signed-in user must be assigned one of the following Microsoft Entra roles:

• Microsoft Entra Backup Reader — For read operations (listing snapshots, viewing jobs, retrieving changes).
• Microsoft Entra Backup Administrator — For write operations (creating preview jobs, creating recovery jobs, canceling jobs).

Limitations

• This feature isn't supported for Entra External ID and Azure AD B2C tenants.
• Backup snapshots are created automatically once per day and retained for five days. You can't create, modify, delete, or export snapshots.
• Not all attributes and linked attributes of the supported object types can be recovered.
• On-premises Active Directory-synced objects can't be recovered through these APIs, though changes are visible in snapshots.
• Job completion time depends on the volume of data and processing complexity. Allow at least 1 hour to complete.
• Recovery to another tenant isn't supported.
• Recovery operations don't generate change notifications through subscriptions or delta records for change tracking. Applications that rely on these mechanisms aren't notified of changes made by recovery jobs.

Throttling

The backup and recovery APIs follow standard Microsoft Graph service-specific throttling limits. Monitor 429 Too Many Requests responses and implement retry logic using the Retry-After header.

Related content

• snapshot resource type
• recoveryJobBase resource type
• recoveryPreviewJob resource type
• recoveryJob resource type