Microsoft Graph Directory Roles provides a REST API to discover, activate, and manage Microsoft Entra ID (formerly Azure Active Directory) directory roles—the RBAC roles that control permissions across Microsoft 365 and Entra. Through the API you can list which roles are active in a tenant, read role definitions from templates, activate built‑in roles, enumerate a role’s members, and add or remove assignments for users, groups, or service principals.
openapi: 3.1.0
info:
title: Microsoft Graph Directoryroles
description: Needs a description.
paths:
/directoryRoles:
description: Provides operations to manage the collection of directoryRole entities.
get:
tags:
- directoryRoles.directoryRole
summary: Microsoft Graph List directoryRoles
description: >-
List the directory roles that are activated in the tenant. This
operation only returns roles that have been activated. A role becomes
activated when an admin activates the role using the Activate
directoryRole API. Not all built-in roles are initially activated. When
assigning a role using the Microsoft Entra admin center, the role
activation step is implicitly done on the admin's behalf. To get the
full list of roles that are available in Microsoft Entra ID, use List
directoryRoleTemplates.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/directoryrole-list?view=graph-rest-1.0
operationId: directoryRoles.directoryRole.ListDirectoryRole
parameters:
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
$ref: >-
#/components/responses/microsoft.graph.directoryRoleCollectionResponse
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
x-ms-docs-operation-type: operation
post:
tags:
- directoryRoles.directoryRole
summary: Microsoft Graph Activate directoryRole
description: >-
Activate a directory role. To read a directory role or update its
members, it must first be activated in the tenant. The Company
Administrators and the implicit user directory roles (User, Guest User,
and Restricted Guest User roles) are activated by default. To access and
assign members to other directory roles, you must first activate it with
its corresponding directory role template ID.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/directoryrole-post-directoryroles?view=graph-rest-1.0
operationId: directoryRoles.directoryRole.CreateDirectoryRole
requestBody:
description: New entity
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.directoryRole'
required: true
responses:
2XX:
description: Created entity
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.directoryRole'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
/directoryRoles/{directoryRole-id}:
description: Provides operations to manage the collection of directoryRole entities.
get:
tags:
- directoryRoles.directoryRole
summary: Microsoft Graph Get directoryRole
description: >-
Retrieve the properties of a directoryRole object. The role must be
activated in tenant for a successful response. 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.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/directoryrole-get?view=graph-rest-1.0
operationId: directoryRoles.directoryRole.GetDirectoryRole
parameters:
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved entity
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.directoryRole'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
patch:
tags:
- directoryRoles.directoryRole
summary: Microsoft Graph Update entity in directoryRoles
operationId: directoryRoles.directoryRole.UpdateDirectoryRole
requestBody:
description: New property values
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.directoryRole'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.directoryRole'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
delete:
tags:
- directoryRoles.directoryRole
summary: Microsoft Graph Delete entity from directoryRoles
operationId: directoryRoles.directoryRole.DeleteDirectoryRole
parameters:
- name: If-Match
in: header
description: ETag
schema:
type: string
responses:
'204':
description: Success
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: directoryRole-id
in: path
description: The unique identifier of directoryRole
required: true
schema:
type: string
x-ms-docs-key-type: directoryRole
/directoryRoles/{directoryRole-id}/members:
description: >-
Provides operations to manage the members property of the
microsoft.graph.directoryRole entity.
get:
tags:
- directoryRoles.directoryObject
summary: Microsoft Graph List members of a directory role
description: >-
Retrieve the list of principals that are assigned to the directory
role. 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.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/directoryrole-list-members?view=graph-rest-1.0
operationId: directoryRoles.ListMembers
parameters:
- name: ConsistencyLevel
in: header
description: >-
Indicates the requested consistency level. Documentation URL:
https://docs.microsoft.com/graph/aad-advanced-queries
schema:
type: string
examples:
example-1:
description: >-
$search and $count queries require the client to set the
ConsistencyLevel HTTP header to 'eventual'.
value: eventual
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
$ref: >-
#/components/responses/microsoft.graph.directoryObjectCollectionResponse
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
x-ms-docs-operation-type: operation
parameters:
- name: directoryRole-id
in: path
description: The unique identifier of directoryRole
required: true
schema:
type: string
x-ms-docs-key-type: directoryRole
/directoryRoles/{directoryRole-id}/members/{directoryObject-id}/$ref:
description: Provides operations to manage the collection of directoryRole entities.
delete:
tags:
- directoryRoles.directoryObject
summary: Microsoft Graph Remove directory role member
description: >-
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.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/directoryrole-delete-member?view=graph-rest-1.0
operationId: directoryRoles.members.DeleteRefDirectoryObject
parameters:
- name: If-Match
in: header
description: ETag
schema:
type: string
responses:
'204':
description: Success
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: directoryRole-id
in: path
description: The unique identifier of directoryRole
required: true
schema:
type: string
x-ms-docs-key-type: directoryRole
- name: directoryObject-id
in: path
description: The unique identifier of directoryObject
required: true
schema:
type: string
x-ms-docs-key-type: directoryObject
/directoryRoles/{directoryRole-id}/members/{directoryObject-id}/graph.application:
description: Casts the previous resource to application.
get:
tags:
- directoryRoles.directoryObject
summary: >-
Microsoft Graph Get the item of type microsoft.graph.directoryObject as microsoft.graph.application
operationId: directoryRoles.GetMembers.AsApplication
parameters:
- name: ConsistencyLevel
in: header
description: >-
Indicates the requested consistency level. Documentation URL:
https://docs.microsoft.com/graph/aad-advanced-queries
schema:
type: string
examples:
example-1:
description: >-
$search and $count queries require the client to set the
ConsistencyLevel HTTP header to 'eventual'.
value: eventual
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Entity result.
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.application'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
parameters:
- name: directoryRole-id
in: path
description: The unique identifier of directoryRole
required: true
schema:
type: string
x-ms-docs-key-type: directoryRole
- name: directoryObject-id
in: path
description: The unique identifier of directoryObject
required: true
schema:
type: string
x-ms-docs-key-type: directoryObject
/directoryRoles/{directoryRole-id}/members/{directoryObject-id}/graph.device:
description: Casts the previous resource to device.
get:
tags:
- directoryRoles.directoryObject
summary: >-
Microsoft Graph Get the item of type microsoft.graph.directoryObject as microsoft.graph.device
operationId: directoryRoles.GetMembers.AsDevice
parameters:
- name: ConsistencyLevel
in: header
description: >-
Indicates the requested consistency level. Documentation URL:
https://docs.microsoft.com/graph/aad-advanced-queries
schema:
type: string
examples:
example-1:
description: >-
$search and $count queries require the client to set the
ConsistencyLevel HTTP header to 'eventual'.
value: eventual
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Entity result.
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.device'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
parameters:
- name: directoryRole-id
in: path
description: The unique identifier of directoryRole
required: true
schema:
type: string
x-ms-docs-key-type: directoryRole
- name: directoryObject-id
in: path
description: The unique identifier of directoryObject
required: true
schema:
type: string
x-ms-docs-key-type: directoryObject
/directoryRoles/{directoryRole-id}/members/{directoryObject-id}/graph.group:
description: Casts the previous resource to group.
get:
tags:
- directoryRoles.directoryObject
summary: >-
Microsoft Graph Get the item of type microsoft.graph.directoryObject as microsoft.graph.group
operationId: directoryRoles.GetMembers.AsGroup
parameters:
- name: ConsistencyLevel
in: header
description: >-
Indicates the requested consistency level. Documentation URL:
https://docs.microsoft.com/graph/aad-advanced-queries
schema:
type: string
examples:
example-1:
description: >-
$search and $count queries require the client to set the
ConsistencyLevel HTTP header to 'eventual'.
value: eventual
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Entity result.
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.group'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
parameters:
- name: directoryRole-id
in: path
description: The unique identifier of directoryRole
required: true
schema:
type: string
x-ms-docs-key-type: directoryRole
- name: directoryObject-id
in: path
description: The unique identifier of directoryObject
required: true
schema:
type: string
x-ms-docs-key-type: directoryObject
/directoryRoles/{directoryRole-id}/members/{directoryObject-id}/graph.orgContact:
description: Casts the previous resource to orgContact.
get:
tags:
- directoryRoles.directoryObject
summary: >-
Microsoft Graph Get the item of type microsoft.graph.directoryObject as microsoft.graph.orgContact
operationId: directoryRoles.GetMembers.AsOrgContact
parameters:
- name: ConsistencyLevel
in: header
description: >-
Indicates the requested consistency level. Documentation URL:
https://docs.microsoft.com/graph/aad-advanced-queries
schema:
type: string
examples:
example-1:
description: >-
$search and $count queries require the client to set the
ConsistencyLevel HTTP header to 'eventual'.
value: eventual
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Entity result.
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.orgContact'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
parameters:
- name: directoryRole-id
in: path
description: The unique identifier of directoryRole
required: true
schema:
type: string
x-ms-docs-key-type: directoryRole
- name: directoryObject-id
in: path
description: The unique identifier of directoryObject
required: true
schema:
type: string
x-ms-docs-key-type: directoryObject
/directoryRoles/{directoryRole-id}/members/{directoryObject-id}/graph.servicePrincipal:
description: Casts the previous resource to servicePrincipal.
get:
tags:
- directoryRoles.directoryObject
summary: >-
Microsoft Graph Get the item of type microsoft.graph.directoryObject as microsoft.graph.servicePrincipal
operationId: directoryRoles.GetMembers.AsServicePrincipal
parameters:
- name: ConsistencyLevel
in: header
description: >-
Indicates the requested consistency level. Documentation URL:
https://docs.microsoft.com/graph/aad-advanced-queries
schema:
type: string
examples:
example-1:
description: >-
$search and $count queries require the client to set the
ConsistencyLevel HTTP header to 'eventual'.
value: eventual
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Entity result.
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.servicePrincipal'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
parameters:
- name: directoryRole-id
in: path
description: The unique identifier of directoryRole
required: true
schema:
type: string
x-ms-docs-key-type: directoryRole
- name: directoryObject-id
in: path
description: The unique identifier of directoryObject
required: true
schema:
type: string
x-ms-docs-key-type: directoryObject
/directoryRoles/{directoryRole-id}/members/{directoryObject-id}/graph.user:
description: Casts the previous resource to user.
get:
tags:
- directoryRoles.directoryObject
summary: >-
Microsoft Graph Get the item of type microsoft.graph.directoryObject as microsoft.graph.user
operationId: directoryRoles.GetMembers.AsUser
parameters:
- name: ConsistencyLevel
in: header
description: >-
Indicates the requested consistency level. Documentation URL:
https://docs.microsoft.com/graph/aad-advanced-queries
schema:
type: string
examples:
example-1:
description: >-
$search and $count queries require the client to set the
ConsistencyLevel HTTP header to 'eventual'.
value: eventual
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Entity result.
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.user'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
parameters:
- name: directoryRole-id
in: path
description: The unique identifier of directoryRole
required: true
schema:
type: string
x-ms-docs-key-type: directoryRole
- name: directoryObject-id
in: path
description: The unique identifier of directoryObject
required: true
schema:
type: string
x-ms-docs-key-type: directoryObject
/directoryRoles/{directoryRole-id}/members/$count:
description: Provides operations to count the resources in the collection.
get:
tags:
- directoryRoles.directoryObject
summary: Microsoft Graph Get the number of the resource
operationId: directoryRoles.members.GetCount-5361
parameters:
- name: ConsistencyLevel
in: header
description: >-
Indicates the requested consistency level. Documentation URL:
https://docs.microsoft.com/graph/aad-advanced-queries
schema:
type: string
examples:
example-1:
description: >-
$search and $count queries require the client to set the
ConsistencyLevel HTTP header to 'eventual'.
value: eventual
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
responses:
2XX:
$ref: '#/components/responses/ODataCountResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
parameters:
- name: directoryRole-id
in: path
description: The unique identifier of directoryRole
required: true
schema:
type: string
x-ms-docs-key-type: directoryRole
/directoryRoles/{directoryRole-id}/members/$ref:
description: Provides operations to manage the collection of directoryRole entities.
get:
tags:
- directoryRoles.directoryObject
summary: Microsoft Graph List members of a directory role
description: >-
Retrieve the list of principals that are assigned to the directory
role. 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.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/directoryrole-list-members?view=graph-rest-1.0
operationId: directoryRoles.ListRefMembers
parameters:
- name: ConsistencyLevel
in: header
description: >-
Indicates the requested consistency level. Documentation URL:
https://docs.microsoft.com/graph/aad-advanced-queries
schema:
type: string
examples:
example-1:
description: >-
$search and $count queries require the client to set the
ConsistencyLevel HTTP header to 'eventual'.
value: eventual
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
$ref: '#/components/responses/StringCollectionResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
x-ms-docs-operation-type: operation
post:
tags:
- directoryRoles.directoryObject
summary: Microsoft Graph Add directory role member
description: >-
Create a new directory role member. 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.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/directoryrole-post-members?view=graph-rest-1.0
operationId: directoryRoles.CreateRefMembers
requestBody:
$ref: '#/components/requestBodies/refPostBody'
responses:
'204':
description: Success
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
delete:
tags:
- directoryRoles.directoryObject
summary: Microsoft Graph Remove directory role member
description: >-
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.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/directoryrole-delete-member?view=graph-rest-1.0
operationId: directoryRoles.DeleteRefMembers
parameters:
- name: If-Match
in: header
description: ETag
schema:
type: string
- name: '@id'
in: query
description: The delete Uri
required: true
schema:
type: string
responses:
'204':
description: Success
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: directoryRole-id
in: path
description: The unique identifier of directoryRole
required: true
schema:
type: string
x-ms-docs-key-type: directoryRole
/directoryRoles/{directoryRole-id}/members/graph.application:
description: Casts the previous resource to application.
get:
tags:
- directoryRoles.directoryObject
summary: >-
Microsoft Graph Get the items of type microsoft.graph.application in the microsoft.graph.directoryObject collection
operationId: directoryRoles.ListMembers.AsApplication
parameters:
- name: ConsistencyLevel
in: header
description: >-
Indicates the requested consistency level. Documentation URL:
https://docs.microsoft.com/graph/aad-advanced-queries
schema:
type: string
examples:
example-1:
description: >-
$search and $count queries require the client to set the
ConsistencyLevel HTTP header to 'eventual'.
value: eventual
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $select
in: query
description: Select properties to be retu
# --- truncated at 32 KB (243 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-graph/refs/heads/main/openapi/directoryroles-openapi-original.yml