directoryRole resource type

Represents an Azure AD directory role. Azure AD directory roles are also known as administrator roles. For more information about directory (administrator) roles, see Assigning administrator roles in Azure AD. 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. 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.


Method Return Type Description
Get directoryRole directoryRole Read properties and relationships of directoryRole object.
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.
List scoped administrators scopedRoleMembership collection List the members of this directory role that are scoped to administrative units, through the scopedRoleMembership object collection.


Property Type Description
description String The description for the directory role. Read-only.
displayName String The display name for the directory role. Read-only.
id String The unique identifier for the directory role. Inherited from directoryObject. Key, Not nullable, Read-only.
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.


Relationship Type Description
members directoryObject collection Users that are members of this directory role. HTTP Methods: GET, POST, DELETE. Read-only. Nullable.
scopedAdministrators scopedRoleMembership collection Administrators of this directory role that are scoped to administrative units. Read-only. Nullable.

JSON representation

Here is a JSON representation of the resource

  "description": "string",
  "displayName": "string",
  "id": "string (identifier)",
  "roleTemplateId": "string"