The directoryRoles.directoryRole API from Microsoft Entra ID (formerly Azure AD) — 4 operation(s) for directoryroles.directoryrole.
Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/azure-ad:azure-ad-directoryroles-directoryrole-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Identity.DirectoryManagement Directory Roles.directory Role…
version: v1.0
servers:
- url: https://graph.microsoft.com/v1.0/
description: Core
security:
- azureaadv2: []
tags:
- name: directoryRoles.directoryRole
paths:
/directoryRoles:
get:
tags:
- directoryRoles.directoryRole
summary: 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: 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'
default:
$ref: '#/components/responses/error'
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
x-ms-docs-operation-type: operation
post:
tags:
- directoryRoles.directoryRole
summary: 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: 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'
default:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
/directoryRoles/{directoryRole-id}:
get:
tags:
- directoryRoles.directoryRole
summary: 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: directoryRole_GetDirectoryRole
parameters:
- name: directoryRole-id
in: path
description: The unique identifier of directoryRole
required: true
style: simple
schema:
type: string
x-ms-docs-key-type: directoryRole
- 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'
default:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
patch:
tags:
- directoryRoles.directoryRole
summary: Update entity in directoryRoles
operationId: directoryRole_UpdateDirectoryRole
parameters:
- name: directoryRole-id
in: path
description: The unique identifier of directoryRole
required: true
style: simple
schema:
type: string
x-ms-docs-key-type: directoryRole
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'
default:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
delete:
tags:
- directoryRoles.directoryRole
summary: Delete entity from directoryRoles
operationId: directoryRole_DeleteDirectoryRole
parameters:
- name: directoryRole-id
in: path
description: The unique identifier of directoryRole
required: true
style: simple
schema:
type: string
x-ms-docs-key-type: directoryRole
- name: If-Match
in: header
description: ETag
style: simple
schema:
type: string
responses:
2XX:
description: Success
default:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
/directoryRoles(roleTemplateId='{roleTemplateId}'):
get:
tags:
- directoryRoles.directoryRole
summary: 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: directoryRole_GetDirectoryRoleGraphBPreRoleTemplateId
parameters:
- name: roleTemplateId
in: path
description: Alternate key of directoryRole
required: true
style: simple
schema:
type:
- string
- 'null'
- 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'
default:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
patch:
tags:
- directoryRoles.directoryRole
summary: Update entity in directoryRoles by roleTemplateId
operationId: directoryRole_UpdateDirectoryRoleGraphBPreRoleTemplateId
parameters:
- name: roleTemplateId
in: path
description: Alternate key of directoryRole
required: true
style: simple
schema:
type:
- string
- 'null'
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'
default:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
delete:
tags:
- directoryRoles.directoryRole
summary: Delete entity from directoryRoles by roleTemplateId
operationId: directoryRole_DeleteDirectoryRoleGraphBPreRoleTemplateId
parameters:
- name: roleTemplateId
in: path
description: Alternate key of directoryRole
required: true
style: simple
schema:
type:
- string
- 'null'
- name: If-Match
in: header
description: ETag
style: simple
schema:
type: string
responses:
2XX:
description: Success
default:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
/directoryRoles/$count:
get:
tags:
- directoryRoles.directoryRole
summary: Get the number of the resource
operationId: directoryRole_GetCount
parameters:
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
responses:
2XX:
$ref: '#/components/responses/ODataCountResponse'
default:
$ref: '#/components/responses/error'
components:
responses:
error:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.ODataErrors.ODataError'
ODataCountResponse:
description: The count of the resource
content:
text/plain:
schema:
$ref: '#/components/schemas/ODataCountResponse'
microsoft.graph.directoryRoleCollectionResponse:
description: Retrieved collection
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.directoryRoleCollectionResponse'
schemas:
microsoft.graph.ODataErrors.InnerError:
type: object
additionalProperties:
type: object
description: The structure of this object is service-specific
microsoft.graph.ODataErrors.MainError:
required:
- code
- message
type: object
properties:
code:
type: string
message:
type: string
x-ms-primary-error-message: true
target:
type:
- string
- 'null'
details:
type: array
items:
$ref: '#/components/schemas/microsoft.graph.ODataErrors.ErrorDetails'
innerError:
$ref: '#/components/schemas/microsoft.graph.ODataErrors.InnerError'
additionalProperties:
type: object
microsoft.graph.directoryRoleCollectionResponse:
title: Collection of directoryRole
type: object
properties:
value:
type: array
items:
$ref: '#/components/schemas/microsoft.graph.directoryRole'
'@odata.nextLink':
type:
- string
- 'null'
additionalProperties:
type: object
microsoft.graph.scopedRoleMembership:
allOf:
- $ref: '#/components/schemas/microsoft.graph.entity'
- title: scopedRoleMembership
type: object
properties:
administrativeUnitId:
type: string
description: Unique identifier for the administrative unit that the directory role is scoped to
roleId:
type: string
description: Unique identifier for the directory role that the member is in.
roleMemberInfo:
$ref: '#/components/schemas/microsoft.graph.identity'
additionalProperties:
type: object
microsoft.graph.directoryObject:
allOf:
- $ref: '#/components/schemas/microsoft.graph.entity'
- title: directoryObject
type: object
properties:
deletedDateTime:
pattern: ^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$
type:
- string
- 'null'
description: Date and time when this object was deleted. Always null when the object hasn't been deleted.
format: date-time
additionalProperties:
type: object
microsoft.graph.identity:
title: identity
type: object
properties:
displayName:
type:
- string
- 'null'
description: The display name of the identity.For drive items, the display name might not always be available or up to date. For example, if a user changes their display name the API might show the new value in a future response, but the items associated with the user don't show up as changed when using delta.
id:
type:
- string
- 'null'
description: Unique identifier for the identity or actor. For example, in the access reviews decisions API, this property might record the id of the principal, that is, the group, user, or application that's subject to review.
additionalProperties:
type: object
microsoft.graph.ODataErrors.ODataError:
required:
- error
type: object
properties:
error:
$ref: '#/components/schemas/microsoft.graph.ODataErrors.MainError'
additionalProperties:
type: object
microsoft.graph.directoryRole:
allOf:
- $ref: '#/components/schemas/microsoft.graph.directoryObject'
- title: directoryRole
type: object
properties:
description:
type:
- string
- 'null'
description: The description for the directory role. Read-only. Supports $filter (eq), $search, $select.
displayName:
type:
- string
- 'null'
description: The display name for the directory role. Read-only. Supports $filter (eq), $search, $select.
roleTemplateId:
type:
- string
- 'null'
description: 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.
members:
type: array
items:
$ref: '#/components/schemas/microsoft.graph.directoryObject'
description: 'Users that are members of this directory role. HTTP Methods: GET, POST, DELETE. Read-only. Nullable. Supports $expand.'
x-ms-navigationProperty: true
scopedMembers:
type: array
items:
$ref: '#/components/schemas/microsoft.graph.scopedRoleMembership'
description: Members of this directory role that are scoped to administrative units. Read-only. Nullable.
x-ms-navigationProperty: true
additionalProperties:
type: object
microsoft.graph.ODataErrors.ErrorDetails:
required:
- code
- message
type: object
properties:
code:
type: string
message:
type: string
target:
type:
- string
- 'null'
additionalProperties:
type: object
microsoft.graph.entity:
title: entity
type: object
properties:
id:
type: string
description: The unique identifier for an entity. Read-only.
additionalProperties:
type: object
ODataCountResponse:
type: integer
format: int32
parameters:
top:
name: $top
in: query
description: Show only the first n items
style: form
explode: false
schema:
minimum: 0
type: integer
example: 50
skip:
name: $skip
in: query
description: Skip the first n items
style: form
explode: false
schema:
minimum: 0
type: integer
filter:
name: $filter
in: query
description: Filter items by property values
style: form
explode: false
schema:
type: string
search:
name: $search
in: query
description: Search items by search phrases
style: form
explode: false
schema:
type: string
count:
name: $count
in: query
description: Include count of items
style: form
explode: false
schema:
type: boolean
securitySchemes:
azureaadv2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
scopes: {}