Soft delete and restore custom roles in Microsoft Entra ID

28/10/2026

Soft delete in Microsoft Entra ID

Microsoft Entra ID supports soft deletion for selected resources. Instead of removing a supported object immediately, the service moves it to a deleted-items collection from which it can be inspected, restored, or permanently deleted.

Many directory objects, such as users, groups, applications, service principals, and administrative units, use the general /directory/deletedItems collection. Other services have dedicated deleted-items containers and APIs. The supported operations, retention behavior, permissions, and restoration semantics vary by resource type, so always check the documentation for the resource you are managing.

For example, restoring an application registration doesn't automatically restore its associated service principal. Each object must be restored separately.

Soft delete for custom role definitions

Microsoft Graph v1.0 supports soft deletion and restoration of custom Microsoft Entra role definitions represented by the unifiedRoleDefinition resource.

Deleting an active custom role moves it to the role-management deleted-items collection:

DELETE /roleManagement/directory/roleDefinitions/{id}

The role doesn't appear in the general /directory/deletedItems collection. Instead, deleted custom roles are available under:

/roleManagement/directory/deletedItems/roleDefinitions

Built-in roles can't be deleted. This capability also requires a Microsoft Entra ID P1 or P2 license.

Permissions and roles

The following table summarizes the least-privileged permissions for the operations used in this post.

Scenario	Endpoint	Method	Permission	Admin Consent	Notes
List active custom roles	`/roleManagement/directory/roleDefinitions`	`GET`	`RoleManagement.Read.Directory`	Yes	Use `$filter=isBuiltIn eq false` to return custom roles only.
List deleted custom roles	`/roleManagement/directory/deletedItems/roleDefinitions`	`GET`	`RoleManagement.Read.Directory`	Yes	For delegated access, Directory Readers is the least-privileged supported built-in role.
Create a custom role	`/roleManagement/directory/roleDefinitions`	`POST`	`RoleManagement.ReadWrite.Directory`	Yes	Requires a supported Microsoft Entra role when using delegated access.
Soft-delete a custom role	`/roleManagement/directory/roleDefinitions/{id}`	`DELETE`	`RoleManagement.ReadWrite.Directory`	Yes	Privileged Role Administrator is the least-privileged supported built-in role for delegated access.
Restore a custom role	`/roleManagement/directory/deletedItems/roleDefinitions/{id}/restore`	`POST`	`RoleManagement.ReadWrite.Directory`	Yes	Returns the restored `unifiedRoleDefinition`.
Permanently delete a custom role	`/roleManagement/directory/deletedItems/roleDefinitions/{id}`	`DELETE`	`RoleManagement.ReadWrite.Directory`	Yes	This operation is irreversible.

RoleManagement.ReadWrite.Directory is a highly privileged permission because it allows an application to manage directory RBAC settings. Grant it only to trusted applications and use it only when write operations are required.

Manage custom roles with Microsoft Graph

The following examples use the Microsoft Graph REST API.

Create a custom role

The following request creates a role that can read the basic properties and membership of administrative units:

POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleDefinitions
Content-type: application/json

{
  "description": "Read basic properties including members on administrative units",
  "displayName": "Administrative Units Reader",
  "rolePermissions":
    [
        {
            "allowedResourceActions": 
            [
                "microsoft.directory/administrativeUnits/members/read",
                "microsoft.directory/administrativeUnits/standard/read"
            ]
        }
    ],
    "isEnabled" : true
}

A successful request returns the created role definition:

{
    "id": "5faaf249-0bbe-4a0f-b15a-1f5041d04a57",
    "description": "Read basic properties including members on administrative units",
    "displayName": "Administrative Units Reader",
    "isBuiltIn": false,
    "isEnabled": true,
    "resourceScopes": [
        "/"
    ],
    "templateId": "5faaf249-0bbe-4a0f-b15a-1f5041d04a57",
    "version": null,
    "rolePermissions": [
        {
            "allowedResourceActions": [
                "microsoft.directory/administrativeUnits/members/read",
                "microsoft.directory/administrativeUnits/standard/read"
            ],
            "condition": null
        }
    ]
}

Save the role definition ID from the response. You will use it in the remaining requests.

List active custom roles

Filter the active role definitions by isBuiltIn to return only custom roles:

GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleDefinitions?$filter=isBuiltIn eq false

The response contains the custom roles in the tenant:

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#roleManagement/directory/roleDefinitions",
    "value": [
        {
            "id": "5faaf249-0bbe-4a0f-b15a-1f5041d04a57",
            "description": "Read basic properties including members on administrative units",
            "displayName": "Administrative Units Reader",
            "isBuiltIn": false,
            "isEnabled": true,
            "resourceScopes": [
                "/"
            ],
            "templateId": "5faaf249-0bbe-4a0f-b15a-1f5041d04a57",
            "version": null,
            "rolePermissions": [
                {
                    "allowedResourceActions": [
                        "microsoft.directory/administrativeUnits/members/read",
                        "microsoft.directory/administrativeUnits/standard/read"
                    ],
                    "condition": null
                }
            ],
            "inheritsPermissionsFrom@odata.context": "https://graph.microsoft.com/v1.0/$metadata#roleManagement/directory/roleDefinitions('5faaf249-0bbe-4a0f-b15a-1f5041d04a57')/inheritsPermissionsFrom",
            "inheritsPermissionsFrom": []
        }
    ]
}

Review role assignments

Before deleting a role, identify who currently receives permissions through it:

GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments?$filter=roleDefinitionId eq '{custom_role_id}'&$expand=principal

Reviewing these assignments helps you understand the impact of deleting the role and gives you a record against which to validate the environment after a restoration.

Soft-delete a custom role

Use the role definition ID to soft-delete the custom role:

DELETE https://graph.microsoft.com/v1.0/roleManagement/directory/roleDefinitions/{custom_role_id}

A successful request returns 204 No Content. The role is removed from the active role definitions collection and becomes available in the dedicated deleted-items collection.

Users should no longer be expected to receive permissions from the deleted role. Verify the effective access of affected principals as part of your operational procedure.

List soft-deleted custom roles

You can list the deleted custom role definitions before restoring or permanently deleting one:

GET https://graph.microsoft.com/v1.0/roleManagement/directory/deletedItems/roleDefinitions

This request requires only RoleManagement.Read.Directory, making it suitable for read-only inventory and recovery tooling.

Restore a soft-deleted custom role

Restore a custom role by sending the following request:

POST https://graph.microsoft.com/v1.0/roleManagement/directory/deletedItems/roleDefinitions/{custom_role_id}/restore

A successful request returns 200 OK and the restored role definition. After restoration, verify the role's properties, assignments, and the effective access of affected principals rather than assuming that the previous authorization state has been fully re-established.

Permanently delete a custom role

To permanently delete a soft-deleted custom role definition, use:

DELETE https://graph.microsoft.com/v1.0/roleManagement/directory/deletedItems/roleDefinitions/{custom_role_id}

A successful request returns 204 No Content. Permanent deletion is irreversible, so confirm that the role is no longer needed and record any configuration required for auditing or future recreation before running this request.

Conclusion

Soft deletion gives administrators a safer way to manage the lifecycle of custom Microsoft Entra roles. A deleted role can be discovered in a dedicated role-management collection, reviewed, and restored through Microsoft Graph instead of being lost immediately.

Treat the feature as a recovery mechanism rather than a substitute for change control. Before deleting a role, inventory its assignments and expected impact. After restoring it, validate the role definition, assignments, and effective access. Reserve permanent deletion for cases in which recovery is no longer required, and protect RoleManagement.ReadWrite.Directory carefully because it grants broad control over directory RBAC settings.

For implementation details, see the Microsoft Graph documentation for: