directoryRole resource type
Namespace: microsoft.graph
Important
APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.
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 unifiedRoleDefinition resource type.
Represents a Microsoft Entra directory role. Microsoft Entra directory roles are also known as administrator roles. For more information about directory (administrator) roles, see Assigning administrator roles in Microsoft Entra ID. With the Microsoft Graph, you can assign users to directory roles to grant them the permissions of the target role. To read a directory role or update its members, it must first be activated in the tenant. Only the Company Administrators directory role is activated by default. To activate other available directory roles, you send a POST request with the ID of the directoryRoleTemplate on which the directory role is based. List directory role templates to get all the other available directory roles. Inherits from directoryObject.
By default, directory roles are scoped to be tenant-wide. However, directory roles (currently only the user account admin and helpdesk admin) may also be scoped to administrative units.
This resource supports:
- Using delta query to track incremental additions, deletions, and updates, by providing a delta function.
Methods
| Method | Return Type | Description |
|---|---|---|
| Get directory role | directoryRole | Read properties and relationships of directoryRole object. |
| List directory roles | directoryRole collection | List the directory roles that are activated in the tenant. |
| Add member | directoryObject | Add a user to the directory role by posting to the members navigation property. |
| List members | directoryObject collection | Get the users that are members of the directory role from the members navigation property. |
| Remove member | directoryObject | Remove a user from the directory role. |
| Activate directory role | directoryRole | Activate a directory role. |
| List scoped members | scopedRoleMembership collection | List the members of this directory role that are scoped to administrative units, through the scopedRoleMembership resource collection. |
| Get delta | directoryRole collection | Get incremental changes for directory roles. |
Properties
| Property | Type | Description |
|---|---|---|
| description | String | The description for the directory role. Read-only. Supports $filter (eq), $search, $select. |
| displayName | String | The display name for the directory role. Read-only. Supports $filter (eq), $search, $select. |
| id | String | The unique identifier for the directory role. Inherited from directoryObject. Key, Not nullable, Read-only. Supports $filter (eq), $select. |
| roleTemplateId | String | The id of the directoryRoleTemplate that this role is based on. The property must be specified when activating a directory role in a tenant with a POST operation. After the directory role has been activated, the property is read only. Supports $filter (eq), $select. |
Relationships
| Relationship | Type | Description |
|---|---|---|
| members | directoryObject collection | Users that are members of this directory role. HTTP Methods: GET, POST, DELETE. Read-only. Nullable. Supports $expand. |
| scopedMembers | scopedRoleMembership collection | Members of this directory role that are scoped to administrative units. Read-only. Nullable. |
JSON representation
The following JSON representation shows the resource type.
{
"description": "string",
"displayName": "string",
"id": "string (identifier)",
"roleTemplateId": "string"
}