Microsoft Graph Directory is the identity and directory surface of Microsoft Graph, providing programmatic access to an organization’s Microsoft Entra ID (formerly Azure Active Directory). Through a single REST endpoint and SDKs, it lets you read and manage users, groups, devices, applications, roles, domains, administrative units, and directory policies, and navigate their relationships.
openapi: 3.1.0
info:
title: Microsoft Graph Directory
description: Needs a description.
paths:
/auditLogs/directoryAudits:
description: >-
Provides operations to manage the directoryAudits property of the
microsoft.graph.auditLogRoot entity.
get:
tags:
- auditLogs.directoryAudit
summary: Microsoft Graph List directoryAudits
description: >-
Get the list of audit logs generated by Microsoft Entra ID. This
includes audit logs generated by various services within Microsoft Entra
ID, including user, app, device and group Management, privileged
identity management (PIM), access reviews, terms of use, identity
protection, password management (self-service and admin password
resets), and self- service group management, and so on.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/directoryaudit-list?view=graph-rest-1.0
operationId: auditLogs.ListDirectoryAudits
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.directoryAuditCollectionResponse
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:
- auditLogs.directoryAudit
summary: Microsoft Graph Create new navigation property to directoryAudits for auditLogs
operationId: auditLogs.CreateDirectoryAudits
requestBody:
description: New navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.directoryAudit'
required: true
responses:
2XX:
description: Created navigation property.
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.directoryAudit'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
/auditLogs/directoryAudits/{directoryAudit-id}:
description: >-
Provides operations to manage the directoryAudits property of the
microsoft.graph.auditLogRoot entity.
get:
tags:
- auditLogs.directoryAudit
summary: Microsoft Graph Get directoryAudit
description: >-
Get a specific Microsoft Entra audit log item. This includes an audit
log item generated by various services within Microsoft Entra ID like
user, application, device and group management, privileged identity
management (PIM), access reviews, terms of use, identity protection,
password management (self-service and admin password resets),
self-service group management, and so on.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/directoryaudit-get?view=graph-rest-1.0
operationId: auditLogs.GetDirectoryAudits
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 navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.directoryAudit'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
patch:
tags:
- auditLogs.directoryAudit
summary: Microsoft Graph Update the navigation property directoryAudits in auditLogs
operationId: auditLogs.UpdateDirectoryAudits
requestBody:
description: New navigation property values
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.directoryAudit'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.directoryAudit'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
delete:
tags:
- auditLogs.directoryAudit
summary: Microsoft Graph Delete navigation property directoryAudits for auditLogs
operationId: auditLogs.DeleteDirectoryAudits
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: directoryAudit-id
in: path
description: The unique identifier of directoryAudit
required: true
schema:
type: string
x-ms-docs-key-type: directoryAudit
/auditLogs/directoryAudits/$count:
description: Provides operations to count the resources in the collection.
get:
tags:
- auditLogs.directoryAudit
summary: Microsoft Graph Get the number of the resource
operationId: auditLogs.directoryAudits.GetCount-fedb
parameters:
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
responses:
2XX:
$ref: '#/components/responses/ODataCountResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
/directory:
description: Provides operations to manage the directory singleton.
get:
tags:
- Directory.directory
summary: Microsoft Graph Get directory
operationId: directory.directory.GetDirectory
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.directory'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
patch:
tags:
- Directory.directory
summary: Microsoft Graph Update directory
operationId: directory.directory.UpdateDirectory
requestBody:
description: New property values
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.directory'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.directory'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
/directory/administrativeUnits:
description: >-
Provides operations to manage the administrativeUnits property of the
microsoft.graph.directory entity.
get:
tags:
- directory.administrativeUnit
summary: Microsoft Graph List administrativeUnits
description: Retrieve a list of administrativeUnit objects.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/directory-list-administrativeunits?view=graph-rest-1.0
operationId: directory.ListAdministrativeUnits
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.administrativeUnitCollectionResponse
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:
- directory.administrativeUnit
summary: Microsoft Graph Create administrativeUnit
description: Create a new administrativeUnit.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/directory-post-administrativeunits?view=graph-rest-1.0
operationId: directory.CreateAdministrativeUnits
requestBody:
description: New navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.administrativeUnit'
required: true
responses:
2XX:
description: Created navigation property.
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.administrativeUnit'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
/directory/administrativeUnits/{administrativeUnit-id}:
description: >-
Provides operations to manage the administrativeUnits property of the
microsoft.graph.directory entity.
get:
tags:
- directory.administrativeUnit
summary: Microsoft Graph Get administrativeUnit
description: >-
Retrieve the properties and relationships of an administrativeUnit
object. The administrativeUnit resource supports extensions, which also
allows you to use the GET operation to get custom properties and
extension data in an administrativeUnit instance.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/administrativeunit-get?view=graph-rest-1.0
operationId: directory.GetAdministrativeUnits
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 navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.administrativeUnit'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
patch:
tags:
- directory.administrativeUnit
summary: Microsoft Graph Update administrativeUnit
description: Update the properties of an administrativeUnit object.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/administrativeunit-update?view=graph-rest-1.0
operationId: directory.UpdateAdministrativeUnits
requestBody:
description: New navigation property values
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.administrativeUnit'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.administrativeUnit'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
delete:
tags:
- directory.administrativeUnit
summary: Microsoft Graph Delete administrativeUnit
description: Delete an administrativeUnit.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/administrativeunit-delete?view=graph-rest-1.0
operationId: directory.DeleteAdministrativeUnits
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: administrativeUnit-id
in: path
description: The unique identifier of administrativeUnit
required: true
schema:
type: string
x-ms-docs-key-type: administrativeUnit
/directory/administrativeUnits/{administrativeUnit-id}/extensions:
description: >-
Provides operations to manage the extensions property of the
microsoft.graph.administrativeUnit entity.
get:
tags:
- directory.administrativeUnit
summary: Microsoft Graph Get extensions from directory
description: >-
The collection of open extensions defined for this administrative unit.
Nullable.
operationId: directory.administrativeUnits.ListExtensions
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.extensionCollectionResponse'
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:
- directory.administrativeUnit
summary: Microsoft Graph Create new navigation property to extensions for directory
operationId: directory.administrativeUnits.CreateExtensions
requestBody:
description: New navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.extension'
required: true
responses:
2XX:
description: Created navigation property.
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.extension'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: administrativeUnit-id
in: path
description: The unique identifier of administrativeUnit
required: true
schema:
type: string
x-ms-docs-key-type: administrativeUnit
/directory/administrativeUnits/{administrativeUnit-id}/extensions/{extension-id}:
description: >-
Provides operations to manage the extensions property of the
microsoft.graph.administrativeUnit entity.
get:
tags:
- directory.administrativeUnit
summary: Microsoft Graph Get extensions from directory
description: >-
The collection of open extensions defined for this administrative unit.
Nullable.
operationId: directory.administrativeUnits.GetExtensions
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 navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.extension'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
patch:
tags:
- directory.administrativeUnit
summary: Microsoft Graph Update the navigation property extensions in directory
operationId: directory.administrativeUnits.UpdateExtensions
requestBody:
description: New navigation property values
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.extension'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.extension'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
delete:
tags:
- directory.administrativeUnit
summary: Microsoft Graph Delete navigation property extensions for directory
operationId: directory.administrativeUnits.DeleteExtensions
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: administrativeUnit-id
in: path
description: The unique identifier of administrativeUnit
required: true
schema:
type: string
x-ms-docs-key-type: administrativeUnit
- name: extension-id
in: path
description: The unique identifier of extension
required: true
schema:
type: string
x-ms-docs-key-type: extension
/directory/administrativeUnits/{administrativeUnit-id}/extensions/$count:
description: Provides operations to count the resources in the collection.
get:
tags:
- directory.administrativeUnit
summary: Microsoft Graph Get the number of the resource
operationId: directory.administrativeUnits.extensions.GetCount-48cb
parameters:
- $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: administrativeUnit-id
in: path
description: The unique identifier of administrativeUnit
required: true
schema:
type: string
x-ms-docs-key-type: administrativeUnit
/directory/administrativeUnits/{administrativeUnit-id}/members:
description: >-
Provides operations to manage the members property of the
microsoft.graph.administrativeUnit entity.
get:
tags:
- directory.administrativeUnit
summary: Microsoft Graph List members
description: >-
Use this API to get the members list (users, groups, or devices) in an
administrative unit.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/administrativeunit-list-members?view=graph-rest-1.0
operationId: directory.administrativeUnits.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
post:
tags:
- directory.administrativeUnit
summary: Microsoft Graph Add a member
description: >-
Use this API to add a member (user, group, or device) to an
administrative unit. Currently it's only possible to add one member at a
time to an administrative unit.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/administrativeunit-post-members?view=graph-rest-1.0
operationId: directory.administrativeUnits.CreateMembers
requestBody:
description: New navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.directoryObject'
required: true
responses:
2XX:
description: Created navigation property.
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.directoryObject'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: administrativeUnit-id
in: path
description: The unique identifier of administrativeUnit
required: true
schema:
type: string
x-ms-docs-key-type: administrativeUnit
/directory/administrativeUnits/{administrativeUnit-id}/members/{directoryObject-id}/$ref:
description: Provides operations to manage the collection of directory entities.
delete:
tags:
- directory.administrativeUnit
summary: Microsoft Graph Remove a member
description: >-
Use this API to remove a member (user, group, or device) from an
administrative unit.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/administrativeunit-delete-members?view=graph-rest-1.0
operationId: directory.administrativeUnits.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: administrativeUnit-id
in: path
description: The unique identifier of administrativeUnit
required: true
schema:
type: string
x-ms-docs-key-type: administrativeUnit
- name: directoryObject-id
in: path
description: The unique identifier of directoryObject
required: true
schema:
type: string
x-ms-docs-key-type: directoryObject
/directory/administrativeUnits/{administrativeUnit-id}/members/{directoryObject-id}/graph.application:
description: Casts the previous resource to application.
get:
tags:
- directory.administrativeUnit
summary: >-
Microsoft Graph Get the item of type microsoft.graph.directoryObject as microsoft.graph.application
operationId: directory.administrativeUnits.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: administrativeUnit-id
in: path
description: The unique identifier of administrativeUnit
required: true
schema:
type: string
x-ms-docs-key-type: administrativeUnit
- name: directoryObject-id
in: path
description: The unique identifier of directoryObject
required: true
schema:
type: string
x-ms-docs-key-type: directoryObject
/directory/administrativeUnits/{administrativeUnit-id}/members/{directoryObject-id}/graph.device:
description: Casts the previous resource to device.
get:
tags:
- directory.administrativeUnit
summary: >-
Microsoft Graph Get the item of type microsoft.graph.directoryObject as microsoft.graph.device
operationId: directory.administrativeUnits.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
# --- truncated at 32 KB (739 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-graph/refs/heads/main/openapi/directory-openapi-original.yml