Remove directory role member

Namespace: microsoft.graph

Note

Microsoft recommends that you use the unified RBAC API instead of this API. The unified RBAC API provides more functionality and flexibility. For more information, see Delete unifiedRoleAssignment.

Remove a member from a directoryRole.

You can use both the object ID and template ID of the directoryRole with this API. The template ID of a built-in role is immutable and can be seen in the role description on the Microsoft Entra admin center. For details, see Role template IDs.

This API is available in the following national cloud deployments.

Global service US Government L4 US Government L5 (DOD) China operated by 21Vianet

Permissions

Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

Permission type Least privileged permissions Higher privileged permissions
Delegated (work or school account) RoleManagement.ReadWrite.Directory Not available.
Delegated (personal Microsoft account) Not supported. Not supported.
Application RoleManagement.ReadWrite.Directory Not available.

Important

In delegated scenarios with work or school accounts, the signed-in user must be assigned a supported Microsoft Entra role or a custom role with a supported role permission. Privileged Role Administrator is the least privileged role supported for this operation.

HTTP request

You can address the directory role using either its id or roleTemplateId.

DELETE /directoryRoles/{role-id}/members/{id}/$ref
DELETE /directoryRoles(roleTemplateId='{roleTemplateId}')/members/{id}/$ref

Caution

If /$ref is not appended to the request and the calling app has permissions to manage the member object, the object will also be deleted from Microsoft Entra ID; otherwise, a 403 Forbidden error is returned. You can restore specific objects through the Restore deleted items API.

Request headers

Name Description
Authorization Bearer {token}. Required. Learn more about authentication and authorization.

Request body

Don't supply a request body for this method.

Response

If successful, this method returns a 204 No Content response code. It doesn't return anything in the response body.

Examples

Example 1: Remove directory role member using role id

Request

In this example, replace f8e85ed8-f66f-4058-b170-3efae8b9c6e5 with the id value of the directory role and bb165b45-151c-4cf6-9911-cd7188912848 with the id value of the user or directory object that you wish to unassign from the directory role.

DELETE https://graph.microsoft.com/v1.0/directoryRoles/f8e85ed8-f66f-4058-b170-3efae8b9c6e5/members/bb165b45-151c-4cf6-9911-cd7188912848/$ref

Response

HTTP/1.1 204 No Content

Example 2: Remove directory role member using roleTemplateId

Request

The following example shows a request. Replace 9f06204d-73c1-4d4c-880a-6edb90606fd8 with the value of your roleTemplateId and bb165b45-151c-4cf6-9911-cd7188912848 with the id value of your user of directory object.

DELETE https://graph.microsoft.com/v1.0/directoryRoles(roleTemplateId='9f06204d-73c1-4d4c-880a-6edb90606fd8')/members/bb165b45-151c-4cf6-9911-cd7188912848/$ref

Response

HTTP/1.1 204 No Content