Microsoft

Microsoft Graph: Directory, organization and roles

Read the tenant (organization), domains, subscribed licences, directory roles and role management, devices, deleted items, schema extensions and guest…

Identity & security#openapi

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

Read the tenant (organization), domains, subscribed licences, directory roles and role management, devices, deleted items, schema extensions and guest invitations.

This listing is one area of Microsoft Graph, the single REST API for Microsoft 365, Outlook, OneDrive, Teams and Microsoft Entra ID. It holds 400 of the area's requests, the most direct ones first, generated from Microsoft's own OpenAPI description of Graph v1.0. The other areas (mail, calendar, files, Teams, users and more) are listed separately on the Microsoft page.

Get an access token

  1. Sign in to the Microsoft Entra admin center and open App registrations > New registration. For a quick test, the Graph Explorer signs you in and shows a token without registering anything.
  2. Under API permissions, add the Microsoft Graph permissions this area needs, for example: Directory.Read.All, RoleManagement.ReadWrite.Directory, Organization.Read.All. Delegated permissions act as the signed-in user; application permissions act as the app itself and need an administrator's consent.
  3. Under Certificates & secrets, create a client secret (keep it out of shared collections).
  4. Get a token from https://login.microsoftonline.com/ /oauth2/v2.0/token: the authorization-code flow for a user, or grant_type=client_credentials with scope=https://graph.microsoft.com/.default for an app. Send it as Authorization: Bearer .

Using these requests

  • Base URL: https://graph.microsoft.com/v1.0. /me/... paths act on the signed-in user; with an application token use /users/{id or userPrincipalName}/... instead.
  • Shape responses with OData query parameters: $select (fields), $filter, $orderby, $top, $expand and $search (some need the ConsistencyLevel: eventual header). Long lists are paged: follow @odata.nextLink.
  • Combine up to 20 requests in one call with POST /$batch.

Common errors

StatusCodeWhat to do
401InvalidAuthenticationTokenThe token is missing, expired or for another resource: get a new one for https://graph.microsoft.com.
403Authorization_RequestDenied / ErrorAccessDeniedAdd the permission listed in the request's docs and grant consent.
404ResourceNotFound / itemNotFoundCheck the id; ids from another user or tenant are not found.
429TooManyRequestsThrottled: wait the Retry-After seconds, then retry.

Docs: Directory, organization and roles overview · Permissions reference · Throttling

Endpoints 400

Devices

  • GETList devices/devicesRetrieve a list of device objects registered in the organization.
  • POSTCreate device/devicesCreate and register a new device in the organization.
  • GETGet device/devices(deviceId=':deviceId')Get the properties and relationships of a device object.
  • DELETEDelete device/devices(deviceId=':deviceId')Delete a registered device.
  • PATCHUpdate device/devices(deviceId=':deviceId')Update the properties of a registered device. Only certain properties of a device can be updated through approved Mobile Device Managment (MDM) apps.
  • GETTrack changes to devices (delta)/devices/delta()Get newly created, updated, or deleted devices without performing a full read of the entire resource collection. For more information, see Use delta query to…
  • POSTGet by ids (device)/devices/getByIdsReturn the directory objects specified in a list of IDs. Only a subset of user properties are returned by default in v1.0. Some common uses for this function…
  • POSTProvision device/devices/provisionProvision a device on behalf of an approved Virtual Desktop Infrastructure (VDI) provider. This action wraps the Zero Touch Deployment (ZTD) protocol to…
  • POSTValidate properties (device)/devices/validatePropertiesValidate that a Microsoft 365 group's display name or mail nickname complies with naming policies. Clients can use this API to determine whether a display…
  • POSTGet available extension properties (device)/devices/getAvailableExtensionPropertiesReturn all directory extension definitions that are registered in a directory, including through multitenant apps. The following entities support extension…
  • GETGet device/devices/:device-idGet the properties and relationships of a device object.
  • DELETEDelete device/devices/:device-idDelete a registered device.
  • PATCHUpdate device/devices/:device-idUpdate the properties of a registered device. Only certain properties of a device can be updated through approved Mobile Device Managment (MDM) apps.
  • POSTRestore device/devices/:device-id/restoreRestore a recently deleted directory object from deleted items. The following types are supported: administrativeUnit application agentIdentityBlueprint…
  • POSTGet member groups (device)/devices/:device-id/getMemberGroupsReturn all the group IDs for the groups that the specified user, group, service principal, organizational contact, device, or directory object is a member of.…
  • POSTGet member objects (device)/devices/:device-id/getMemberObjectsReturn all IDs for the groups, administrative units, and directory roles that an object of one of the following types is a member of: user group service…
  • POSTCheck member groups (device)/devices/:device-id/checkMemberGroupsCheck for membership in a specified list of group IDs, and return from that list the IDs of groups where a specified object is a member. The specified object…
  • POSTCheck member objects (device)/devices/:device-id/checkMemberObjects
  • GETGet transitive member of/devices/:device-id/transitiveMemberOfGet the groups and administrative units that the device is a member of. This API request is transitive, and will also return all groups and administrative…
  • GETGet group/devices/:device-id/transitiveMemberOf/graph.groupGet the groups and administrative units that the device is a member of. This API request is transitive, and will also return all groups and administrative…

Domains

  • GETList domains/domainsRetrieve a list of domain objects.
  • POSTCreate domain/domainsAdds a domain to the tenant. Important: You cannot use an associated domain with your Microsoft Entra tenant until ownership is verified. See List…
  • GETGet domain/domains/:domain-idRetrieve the properties and relationships of domain object.
  • DELETEDelete domain/domains/:domain-idDelete a domain from a tenant.
  • PATCHUpdate domain/domains/:domain-idUpdate the properties of domain object. Only verified domains can be updated.
  • POSTCreate verify/domains/:domain-id/verifyValidate the ownership of a domain. This operation only applies to an unverified domain. For an unverified domain, the isVerified property is false.
  • POSTCreate promote/domains/:domain-id/promotePromote a verified subdomain to the root domain. A verified domain has its isVerified property set to true.
  • GETGet root domain/domains/:domain-id/rootDomainGet the root domain of a subdomain. This API returns a single object.
  • POSTCreate force delete/domains/:domain-id/forceDeleteDelete a domain using an asynchronous long-running operation. Before performing this operation, you must update or remove any references to Exchange as the…
  • GETList domain name references/domains/:domain-id/domainNameReferencesRetrieve a list of directoryObject with a reference to the domain. The returned list will contain all directory objects that have a dependency on the domain.
  • GETList verification dns records/domains/:domain-id/verificationDnsRecordsRetrieve a list of domainDnsRecord objects. You cannot use an associated domain with your Microsoft Entra tenant until ownership is verified. To verify the…
  • POSTCreate verification dns record/domains/:domain-id/verificationDnsRecords
  • GETGet federation configuration/domains/:domain-id/federationConfigurationRead the properties of the internalDomainFederation objects for the domain. This API returns only one object in the collection.
  • POSTCreate federation configuration/domains/:domain-id/federationConfigurationCreate a new internalDomainFederation object.
  • GETList service configuration records/domains/:domain-id/serviceConfigurationRecordsRetrieves a list of domainDnsRecord objects needed to enable services for the domain. Use the returned list to add records to the zone file of the domain.…
  • POSTCreate service configuration record/domains/:domain-id/serviceConfigurationRecords

Contacts

  • GETList contacts/contactsGet the list of organizational contacts for this organization.
  • GETTrack changes to contacts (delta)/contacts/delta()Get newly created, updated, or deleted organizational contacts without having to perform a full read of the entire collection. For more information, see Use…
  • POSTGet by ids (contact)/contacts/getByIdsReturn the directory objects specified in a list of IDs. Only a subset of user properties are returned by default in v1.0. Some common uses for this function…
  • POSTValidate properties (contact)/contacts/validatePropertiesValidate that a Microsoft 365 group's display name or mail nickname complies with naming policies. Clients can use this API to determine whether a display…
  • POSTGet available extension properties (contact)/contacts/getAvailableExtensionPropertiesReturn all directory extension definitions that are registered in a directory, including through multitenant apps. The following entities support extension…
  • GETGet contact/contacts/:orgContact-idGet the properties and relationships of an organizational contact.
  • DELETEDelete contact/contacts/:orgContact-id
  • PATCHUpdate contact/contacts/:orgContact-id
  • GETGet manager/contacts/:orgContact-id/managerGet this organizational contact's manager.
  • POSTRestore contact/contacts/:orgContact-id/restoreRestore a recently deleted directory object from deleted items. The following types are supported: administrativeUnit application agentIdentityBlueprint…
  • POSTGet member groups (contact)/contacts/:orgContact-id/getMemberGroupsReturn all the group IDs for the groups that the specified user, group, service principal, organizational contact, device, or directory object is a member of.…
  • POSTGet member objects (contact)/contacts/:orgContact-id/getMemberObjectsReturn all IDs for the groups, administrative units, and directory roles that an object of one of the following types is a member of: user group service…
  • POSTCheck member groups (contact)/contacts/:orgContact-id/checkMemberGroupsCheck for membership in a specified list of group IDs, and return from that list the IDs of groups where a specified object is a member. The specified object…
  • POSTCheck member objects (contact)/contacts/:orgContact-id/checkMemberObjects
  • GETGet transitive member of/contacts/:orgContact-id/transitiveMemberOfGet groups that this organizational contact is a member of. The API request is transitive, and returns all groups the organizational contact is a nested…
  • POSTRetry service provisioning (contact)/contacts/:orgContact-id/retryServiceProvisioningRetry the orgContact service provisioning.
  • GETList service provisioning errors/contacts/:orgContact-id/serviceProvisioningErrorsErrors published by a federated service describing a non-transient, service-specific error regarding the properties or link from an organizational contact…
  • GETGet group/contacts/:orgContact-id/transitiveMemberOf/graph.group

Contracts

  • GETList contracts/contractsRetrieve a list of contract objects associated to a partner tenant.
  • POSTCreate contract/contracts
  • GETTrack changes to contracts (delta)/contracts/delta()Get newly created, updated, or deleted directory objects without performing a full read of the entire directoryObject collection. For more information, see…
  • POSTGet by ids (contract)/contracts/getByIdsReturn the directory objects specified in a list of IDs. Only a subset of user properties are returned by default in v1.0. Some common uses for this function…
  • POSTValidate properties (contract)/contracts/validatePropertiesValidate that a Microsoft 365 group's display name or mail nickname complies with naming policies. Clients can use this API to determine whether a display…
  • POSTGet available extension properties (contract)/contracts/getAvailableExtensionPropertiesReturn all directory extension definitions that are registered in a directory, including through multitenant apps. The following entities support extension…
  • GETGet contract/contracts/:contract-idRetrieve the properties and relationships of contract object.
  • DELETEDelete contract/contracts/:contract-id
  • PATCHUpdate contract/contracts/:contract-id
  • POSTRestore contract/contracts/:contract-id/restoreRestore a recently deleted directory object from deleted items. The following types are supported: administrativeUnit application agentIdentityBlueprint…
  • POSTGet member groups (contract)/contracts/:contract-id/getMemberGroupsReturn all the group IDs for the groups that the specified user, group, service principal, organizational contact, device, or directory object is a member of.…
  • POSTGet member objects (contract)/contracts/:contract-id/getMemberObjectsReturn all IDs for the groups, administrative units, and directory roles that an object of one of the following types is a member of: user group service…
  • POSTCheck member groups (contract)/contracts/:contract-id/checkMemberGroupsCheck for membership in a specified list of group IDs, and return from that list the IDs of groups where a specified object is a member. The specified object…
  • POSTCheck member objects (contract)/contracts/:contract-id/checkMemberObjects

Directory

  • GETGet directory/directory
  • PATCHUpdate directory/directory
  • GETGet directory/directory/subscriptions(commerceSubscriptionId=':commerceSubscriptionId')Get a specific commercial subscription that an organization acquired.
  • DELETEDelete directory/directory/subscriptions(commerceSubscriptionId=':commerceSubscriptionId')
  • PATCHUpdate directory/directory/subscriptions(commerceSubscriptionId=':commerceSubscriptionId')

Invitations

  • GETList invitations/invitations
  • POSTCreate invitation/invitationsUse this API to create a new invitation or reset the redemption status for a guest user who already redeemed their invitation. The invitation adds the…
  • GETList invited user sponsors/invitations/invitedUserSponsorsThe users or groups who are sponsors of the invited user. Sponsors are users and groups that are responsible for guest users' privileges in the tenant and for…
  • GETGet invited user sponsor/invitations/invitedUserSponsors/:directoryObject-idThe users or groups who are sponsors of the invited user. Sponsors are users and groups that are responsible for guest users' privileges in the tenant and for…

Organization

  • GETGet organization/organizationRetrieve a list of organization objects. There's only one organization object in the collection.
  • POSTCreate organization/organization
  • GETTrack changes to organization (delta)/organization/delta()Get newly created, updated, or deleted directory objects without performing a full read of the entire directoryObject collection. For more information, see…
  • POSTGet by ids (organization)/organization/getByIdsReturn the directory objects specified in a list of IDs. Only a subset of user properties are returned by default in v1.0. Some common uses for this function…
  • POSTValidate properties (organization)/organization/validatePropertiesValidate that a Microsoft 365 group's display name or mail nickname complies with naming policies. Clients can use this API to determine whether a display…
  • POSTGet available extension properties (organization)/organization/getAvailableExtensionPropertiesReturn all directory extension definitions that are registered in a directory, including through multitenant apps. The following entities support extension…
  • GETGet organization/organization/:organization-idGet the properties and relationships of the currently authenticated organization. Since the organization resource supports extensions, you can also use the…
  • DELETEDelete organization/organization/:organization-id
  • PATCHUpdate organization/organization/:organization-idUpdate the properties of the currently authenticated organization. In this case, organization is defined as a collection of exactly one record, and so its ID…
  • POSTRestore organization/organization/:organization-id/restoreRestore a recently deleted directory object from deleted items. The following types are supported: administrativeUnit application agentIdentityBlueprint…
  • GETList extensions/organization/:organization-id/extensionsThe collection of open extensions defined for the organization. Read-only. Nullable.
  • POSTCreate extension/organization/:organization-id/extensions
  • POSTGet member groups (organization)/organization/:organization-id/getMemberGroupsReturn all the group IDs for the groups that the specified user, group, service principal, organizational contact, device, or directory object is a member of.…
  • POSTGet member objects (organization)/organization/:organization-id/getMemberObjectsReturn all IDs for the groups, administrative units, and directory roles that an object of one of the following types is a member of: user group service…
  • POSTCheck member groups (organization)/organization/:organization-id/checkMemberGroupsCheck for membership in a specified list of group IDs, and return from that list the IDs of groups where a specified object is a member. The specified object…
  • POSTCheck member objects (organization)/organization/:organization-id/checkMemberObjects
  • GETGet certificate based auth configuration/organization/:organization-id/certificateBasedAuthConfigurationGet a list of certificateBasedAuthConfiguration objects.
  • POSTCreate certificate based auth configuration/organization/:organization-id/certificateBasedAuthConfigurationCreate a new certificateBasedAuthConfiguration object.
  • POSTSet mobile device management authority (organization)/organization/:organization-id/setMobileDeviceManagementAuthoritySet mobile device management authority

Group settings

  • GETGet group settings/groupSettingsRetrieve a list of tenant-level or group-specific group settings objects.
  • POSTCreate group settings/groupSettingsCreate a new group setting based on the templates available in groupSettingTemplates. These settings can be at the tenant-level or at the group level. The…
  • GETGet group settings/groupSettings/:groupSetting-idRetrieve the properties of a specific group setting object. The setting can be a tenant-level or group-specific setting.
  • DELETEDelete group settings/groupSettings/:groupSetting-idDelete a tenant-level or group-specific groupSetting object.
  • PATCHUpdate group settings/groupSettings/:groupSetting-idUpdate the properties of a groupSetting object for tenant-wide group settings or a specific group setting.

Directory roles

  • GETList directory roles/directoryRolesList 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…
  • POSTCreate directory role/directoryRolesActivate 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…
  • GETGet directory role/directoryRoles(roleTemplateId=':roleTemplateId')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…
  • DELETEDelete directory role/directoryRoles(roleTemplateId=':roleTemplateId')
  • PATCHUpdate directory role/directoryRoles(roleTemplateId=':roleTemplateId')
  • GETTrack changes to directory roles (delta)/directoryRoles/delta()Get newly created, updated, or deleted directory roles without having to perform a full read of the entire resource collection. For more information, see Use…
  • POSTGet by ids (directory role)/directoryRoles/getByIdsReturn the directory objects specified in a list of IDs. Only a subset of user properties are returned by default in v1.0. Some common uses for this function…
  • POSTValidate properties (directory role)/directoryRoles/validatePropertiesValidate that a Microsoft 365 group's display name or mail nickname complies with naming policies. Clients can use this API to determine whether a display…
  • POSTGet available extension properties (directory role)/directoryRoles/getAvailableExtensionPropertiesReturn all directory extension definitions that are registered in a directory, including through multitenant apps. The following entities support extension…
  • GETGet directory role/directoryRoles/:directoryRole-idRetrieve 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…
  • DELETEDelete directory role/directoryRoles/:directoryRole-id
  • PATCHUpdate directory role/directoryRoles/:directoryRole-id
  • POSTRestore directory role/directoryRoles/:directoryRole-id/restoreRestore a recently deleted directory object from deleted items. The following types are supported: administrativeUnit application agentIdentityBlueprint…
  • GETList scoped members/directoryRoles/:directoryRole-id/scopedMembersRetrieve a list of scopedRoleMembership objects for a directory role.
  • POSTCreate scoped member/directoryRoles/:directoryRole-id/scopedMembers
  • POSTGet member groups (directory role)/directoryRoles/:directoryRole-id/getMemberGroupsReturn all the group IDs for the groups that the specified user, group, service principal, organizational contact, device, or directory object is a member of.…
  • POSTGet member objects (directory role)/directoryRoles/:directoryRole-id/getMemberObjectsReturn all IDs for the groups, administrative units, and directory roles that an object of one of the following types is a member of: user group service…
  • POSTCheck member groups (directory role)/directoryRoles/:directoryRole-id/checkMemberGroupsCheck for membership in a specified list of group IDs, and return from that list the IDs of groups where a specified object is a member. The specified object…
  • POSTCheck member objects (directory role)/directoryRoles/:directoryRole-id/checkMemberObjects

Role management

  • GETGet role management/roleManagement
  • PATCHUpdate role management/roleManagement

Subscribed skus

  • GETList subscribed skus/subscribedSkusGet the list of commercial subscriptions that an organization has acquired. For the mapping of license names as displayed on the Microsoft Entra admin center…
  • POSTCreate subscribed sku/subscribedSkus
  • GETGet subscribed sku/subscribedSkus/:subscribedSku-idGet a specific commercial subscription that an organization has acquired.
  • DELETEDelete subscribed sku/subscribedSkus/:subscribedSku-id
  • PATCHUpdate subscribed sku/subscribedSkus/:subscribedSku-id

Directory objects

  • GETList directory objects/directoryObjects
  • POSTCreate directory object/directoryObjects
  • GETTrack changes to directory objects (delta)/directoryObjects/delta()Get newly created, updated, or deleted directory objects without performing a full read of the entire directoryObject collection. For more information, see…
  • POSTGet by ids (directory object)/directoryObjects/getByIdsReturn the directory objects specified in a list of IDs. Only a subset of user properties are returned by default in v1.0. Some common uses for this function…
  • POSTValidate properties (directory object)/directoryObjects/validatePropertiesValidate that a Microsoft 365 group's display name or mail nickname complies with naming policies. Clients can use this API to determine whether a display…
  • POSTGet available extension properties (directory object)/directoryObjects/getAvailableExtensionPropertiesReturn all directory extension definitions that are registered in a directory, including through multitenant apps. The following entities support extension…
  • GETGet directory object/directoryObjects/:directoryObject-idRetrieve the properties and relationships of a directoryObject object.
  • DELETEDelete directory object/directoryObjects/:directoryObject-idDelete a directory object, for example, a group, user, application, or service principal.
  • PATCHUpdate directory object/directoryObjects/:directoryObject-id
  • POSTRestore directory object/directoryObjects/:directoryObject-id/restoreRestore a recently deleted directory object from deleted items. The following types are supported: administrativeUnit application agentIdentityBlueprint…
  • POSTGet member groups (directory object)/directoryObjects/:directoryObject-id/getMemberGroupsReturn all the group IDs for the groups that the specified user, group, service principal, organizational contact, device, or directory object is a member of.…
  • POSTGet member objects (directory object)/directoryObjects/:directoryObject-id/getMemberObjectsReturn all IDs for the groups, administrative units, and directory roles that an object of one of the following types is a member of: user group service…
  • POSTCheck member groups (directory object)/directoryObjects/:directoryObject-id/checkMemberGroupsCheck for membership in a specified list of group IDs, and return from that list the IDs of groups where a specified object is a member. The specified object…
  • POSTCheck member objects (directory object)/directoryObjects/:directoryObject-id/checkMemberObjects

Domain dns records

  • GETList domain dns records/domainDnsRecords
  • POSTCreate domain dns record/domainDnsRecords
  • GETGet domain dns record/domainDnsRecords/:domainDnsRecord-id
  • DELETEDelete domain dns record/domainDnsRecords/:domainDnsRecord-id
  • PATCHUpdate domain dns record/domainDnsRecords/:domainDnsRecord-id

Schema extensions

  • GETList schema extensions/schemaExtensionsGet a list of schemaExtension objects in your tenant. The schema extensions can be InDevelopment, Available, or Deprecated and includes schema extensions:
  • POSTCreate schema extension/schemaExtensionsCreate a new schemaExtension definition and its associated schema extension property to extend a supporting resource type. Schema extensions let you add…
  • GETGet schema extension/schemaExtensions/:schemaExtension-id
  • DELETEDelete schema extension/schemaExtensions/:schemaExtension-idDelete the definition of a schema extension. Only the app that created the schema extension (owner app) can delete the schema extension definition, and only…
  • PATCHUpdate schema extension/schemaExtensions/:schemaExtension-idUpdate properties in the definition of the specified schemaExtension. Additive updates to the extension can only be made when the extension is in the…

Group setting templates

  • GETList group setting templates/groupSettingTemplatesGroup setting templates represents a set of templates from which group settings may be created and used within a tenant. This operation retrieves the list of…
  • POSTCreate group setting template/groupSettingTemplates
  • GETTrack changes to group setting templates (delta)/groupSettingTemplates/delta()Get newly created, updated, or deleted directory objects without performing a full read of the entire directoryObject collection. For more information, see…
  • POSTGet by ids (group setting template)/groupSettingTemplates/getByIdsReturn the directory objects specified in a list of IDs. Only a subset of user properties are returned by default in v1.0. Some common uses for this function…
  • POSTValidate properties (group setting template)/groupSettingTemplates/validatePropertiesValidate that a Microsoft 365 group's display name or mail nickname complies with naming policies. Clients can use this API to determine whether a display…
  • POSTGet available extension properties (group setting template)/groupSettingTemplates/getAvailableExtensionPropertiesReturn all directory extension definitions that are registered in a directory, including through multitenant apps. The following entities support extension…
  • GETGet group setting template/groupSettingTemplates/:groupSettingTemplate-idA group setting template represents a template of settings from which settings may be created within a tenant. This operation allows retrieval of the…
  • DELETEDelete group setting template/groupSettingTemplates/:groupSettingTemplate-id
  • PATCHUpdate group setting template/groupSettingTemplates/:groupSettingTemplate-id
  • POSTRestore group setting template/groupSettingTemplates/:groupSettingTemplate-id/restoreRestore a recently deleted directory object from deleted items. The following types are supported: administrativeUnit application agentIdentityBlueprint…
  • POSTGet member groups (group setting template)/groupSettingTemplates/:groupSettingTemplate-id/getMemberGroupsReturn all the group IDs for the groups that the specified user, group, service principal, organizational contact, device, or directory object is a member of.…
  • POSTGet member objects (group setting template)/groupSettingTemplates/:groupSettingTemplate-id/getMemberObjectsReturn all IDs for the groups, administrative units, and directory roles that an object of one of the following types is a member of: user group service…
  • POSTCheck member groups (group setting template)/groupSettingTemplates/:groupSettingTemplate-id/checkMemberGroupsCheck for membership in a specified list of group IDs, and return from that list the IDs of groups where a specified object is a member. The specified object…
  • POSTCheck member objects (group setting template)/groupSettingTemplates/:groupSettingTemplate-id/checkMemberObjects

Scoped role memberships

  • GETList scoped role memberships/scopedRoleMemberships
  • POSTCreate scoped role membership/scopedRoleMemberships
  • GETGet scoped role membership/scopedRoleMemberships/:scopedRoleMembership-id
  • DELETEDelete scoped role membership/scopedRoleMemberships/:scopedRoleMembership-id
  • PATCHUpdate scoped role membership/scopedRoleMemberships/:scopedRoleMembership-id

Directory role templates

  • GETList directory role templates/directoryRoleTemplatesRetrieve a list of directoryRoleTemplate objects.
  • POSTCreate directory role template/directoryRoleTemplates
  • GETTrack changes to directory role templates (delta)/directoryRoleTemplates/delta()Get newly created, updated, or deleted directory objects without performing a full read of the entire directoryObject collection. For more information, see…
  • POSTGet by ids (directory role template)/directoryRoleTemplates/getByIdsReturn the directory objects specified in a list of IDs. Only a subset of user properties are returned by default in v1.0. Some common uses for this function…
  • POSTValidate properties (directory role template)/directoryRoleTemplates/validatePropertiesValidate that a Microsoft 365 group's display name or mail nickname complies with naming policies. Clients can use this API to determine whether a display…
  • POSTGet available extension properties (directory role template)/directoryRoleTemplates/getAvailableExtensionPropertiesReturn all directory extension definitions that are registered in a directory, including through multitenant apps. The following entities support extension…
  • GETGet directory role template/directoryRoleTemplates/:directoryRoleTemplate-idRetrieve the properties and relationships of a directoryroletemplate object.
  • DELETEDelete directory role template/directoryRoleTemplates/:directoryRoleTemplate-id
  • PATCHUpdate directory role template/directoryRoleTemplates/:directoryRoleTemplate-id
  • POSTRestore directory role template/directoryRoleTemplates/:directoryRoleTemplate-id/restoreRestore a recently deleted directory object from deleted items. The following types are supported: administrativeUnit application agentIdentityBlueprint…
  • POSTGet member groups (directory role template)/directoryRoleTemplates/:directoryRoleTemplate-id/getMemberGroupsReturn all the group IDs for the groups that the specified user, group, service principal, organizational contact, device, or directory object is a member of.…
  • POSTGet member objects (directory role template)/directoryRoleTemplates/:directoryRoleTemplate-id/getMemberObjectsReturn all IDs for the groups, administrative units, and directory roles that an object of one of the following types is a member of: user group service…
  • POSTCheck member groups (directory role template)/directoryRoleTemplates/:directoryRoleTemplate-id/checkMemberGroupsCheck for membership in a specified list of group IDs, and return from that list the IDs of groups where a specified object is a member. The specified object…
  • POSTCheck member objects (directory role template)/directoryRoleTemplates/:directoryRoleTemplate-id/checkMemberObjects

Group lifecycle policies

  • GETList group lifecycle policies/groupLifecyclePoliciesList all the groupLifecyclePolicies.
  • POSTCreate group lifecycle policy/groupLifecyclePoliciesCreates a new groupLifecyclePolicy. Only one policy exists in the tenant.
  • GETGet group lifecycle policy/groupLifecyclePolicies/:groupLifecyclePolicy-idRetrieve the properties and relationships of a groupLifecyclePolicies object.
  • DELETEDelete group lifecycle policy/groupLifecyclePolicies/:groupLifecyclePolicy-idDelete a groupLifecyclePolicy.
  • PATCHUpdate group lifecycle policy/groupLifecyclePolicies/:groupLifecyclePolicy-idUpdate the properties of a groupLifecyclePolicygroupLifecyclePolicy resource type object.
  • POSTAdd group (group lifecycle policy)/groupLifecyclePolicies/:groupLifecyclePolicy-id/addGroupAdd a group to a groupLifecyclePolicy. This action is supported only if the managedGroupTypes property of the policy is set to Selected.
  • POSTRemove group (group lifecycle policy)/groupLifecyclePolicies/:groupLifecyclePolicy-id/removeGroupRemoves a group from a lifecycle policy.

Directory: recovery

  • GETGet recovery/directory/recovery
  • DELETEDelete recovery/directory/recovery
  • PATCHUpdate recovery/directory/recovery
  • GETList jobs/directory/recovery/jobsGet a list of all recovery recoveryJobBase objects (both preview and recovery jobs) across all snapshots for the tenant.
  • POSTCreate job/directory/recovery/jobs
  • GETList snapshots/directory/recovery/snapshotsGet a list of available backup snapshot objects for the tenant. Snapshots represent points in time to which the tenant can be restored.
  • POSTCreate snapshot/directory/recovery/snapshots
  • GETGet snapshot/directory/recovery/snapshots/:snapshot-idCollection of backup snapshots available for the tenant.
  • DELETEDelete snapshot/directory/recovery/snapshots/:snapshot-id
  • PATCHUpdate snapshot/directory/recovery/snapshots/:snapshot-id
  • GETGet job/directory/recovery/jobs/:recoveryJobBase-idCollection of all recovery jobs (both preview and recovery) for the tenant.
  • DELETEDelete job/directory/recovery/jobs/:recoveryJobBase-id
  • PATCHUpdate job/directory/recovery/jobs/:recoveryJobBase-id

Directory: deleted items

  • GETList deleted items/directory/deletedItemsRetrieve the properties of a recently deleted directory object from deleted items. The following types are supported: administrativeUnit application…
  • POSTGet by ids (deleted item)/directory/deletedItems/getByIdsReturn the directory objects specified in a list of IDs. Only a subset of user properties are returned by default in v1.0. Some common uses for this function…
  • GETGet user/directory/deletedItems/graph.user
  • GETGet group/directory/deletedItems/graph.groupRetrieve a list of recently deleted directory objects from deleted items. The following types are supported: administrativeUnit application…
  • GETGet device/directory/deletedItems/graph.device
  • GETGet application/directory/deletedItems/graph.application
  • POSTValidate properties (deleted item)/directory/deletedItems/validatePropertiesValidate that a Microsoft 365 group's display name or mail nickname complies with naming policies. Clients can use this API to determine whether a display…
  • GETGet service principal/directory/deletedItems/graph.servicePrincipal
  • GETGet administrative unit/directory/deletedItems/graph.administrativeUnit
  • POSTGet available extension properties (deleted item)/directory/deletedItems/getAvailableExtensionPropertiesReturn all directory extension definitions that are registered in a directory, including through multitenant apps. The following entities support extension…
  • GETGet deleted item/directory/deletedItems/:directoryObject-idRetrieve the properties of a recently deleted directory object from deleted items. The following types are supported: administrativeUnit application…
  • DELETEDelete deleted item/directory/deletedItems/:directoryObject-idPermanently delete a recently deleted directory object from deleted items. The following types are supported: application agentIdentityBlueprint agentIdentity…
  • POSTRestore deleted item/directory/deletedItems/:directoryObject-id/restoreRestore a recently deleted directory object from deleted items. The following types are supported: administrativeUnit application agentIdentityBlueprint…
  • GETGet user/directory/deletedItems/:directoryObject-id/graph.user

Directory: attribute sets

  • GETList attribute sets/directory/attributeSetsGet a list of the attributeSet objects and their properties.
  • POSTCreate attribute set/directory/attributeSetsCreate a new attributeSet object.
  • GETGet attribute set/directory/attributeSets/:attributeSet-idRead the properties and relationships of an attributeSet object.
  • DELETEDelete attribute set/directory/attributeSets/:attributeSet-id
  • PATCHUpdate attribute set/directory/attributeSets/:attributeSet-idUpdate the properties of an attributeSet object.

Directory: subscriptions

  • GETList subscriptions/directory/subscriptionsGet the list of commercial subscriptions that an organization acquired.
  • POSTCreate subscription/directory/subscriptions
  • GETGet subscription/directory/subscriptions/:companySubscription-idGet a specific commercial subscription that an organization acquired.
  • DELETEDelete subscription/directory/subscriptions/:companySubscription-id
  • PATCHUpdate subscription/directory/subscriptions/:companySubscription-id

Invitations: invited user

  • GETGet invited user/invitations/invitedUserThe user created as part of the invitation creation. Read-only. The id property is required in the request body to reset a redemption status.
  • GETGet mailbox settings/invitations/invitedUser/mailboxSettingsSettings for the primary mailbox of the signed-in user. You can get or update settings for sending automatic replies to incoming messages, locale, and time…
  • PATCHUpdate mailbox settings/invitations/invitedUser/mailboxSettings
  • GETList service provisioning errors/invitations/invitedUser/serviceProvisioningErrorsErrors published by a federated service describing a nontransient, service-specific error regarding the properties or link from a user object. Supports…

Role management: directory

  • GETGet directory/roleManagement/directory
  • DELETEDelete directory/roleManagement/directory
  • PATCHUpdate directory/roleManagement/directory
  • GETList deleted items/roleManagement/directory/deletedItemsContainer for custom role definitions that have been soft-deleted from Microsoft Entra directory role management.
  • DELETEDelete deleted items/roleManagement/directory/deletedItems
  • PATCHUpdate deleted items/roleManagement/directory/deletedItems
  • GETList role assignments/roleManagement/directory/roleAssignmentsGet a list of unifiedRoleAssignment objects for the RBAC provider. The following RBAC providers are currently supported: directory (Microsoft Entra ID)…
  • POSTCreate role assignment/roleManagement/directory/roleAssignmentsCreate a new unifiedRoleAssignment object.
  • GETList role definitions/roleManagement/directory/roleDefinitionsGet a list of unifiedRoleDefinition objects for the provider. The following RBAC providers are currently supported: directory (Microsoft Entra ID) entitlement…
  • POSTCreate role definition/roleManagement/directory/roleDefinitionsCreate a new custom unifiedRoleDefinition object. This feature requires a Microsoft Entra ID P1 or P2 license.
  • GETList resource namespaces/roleManagement/directory/resourceNamespaces
  • POSTCreate resource namespace/roleManagement/directory/resourceNamespaces
  • GETList role assignment schedules/roleManagement/directory/roleAssignmentSchedulesGet the schedules for active role assignment operations.
  • POSTCreate role assignment schedule/roleManagement/directory/roleAssignmentSchedules
  • GETList role eligibility schedules/roleManagement/directory/roleEligibilitySchedulesGet the unifiedRoleEligibilitySchedule resources from the roleEligibilitySchedules navigation property.
  • POSTCreate role eligibility schedule/roleManagement/directory/roleEligibilitySchedules
  • GETList role assignment schedule requests/roleManagement/directory/roleAssignmentScheduleRequestsRetrieve the requests for active role assignments to principals. The active assignments include those made through assignments and activation requests, and…
  • POSTCreate role assignment schedule request/roleManagement/directory/roleAssignmentScheduleRequestsIn PIM, carry out the following operations through the unifiedRoleAssignmentScheduleRequest object: To call this API to update, renew, and extend assignments…
  • GETList role assignment schedule instances/roleManagement/directory/roleAssignmentScheduleInstancesGet the instances of active role assignments in your tenant. The active assignments include those made through assignments and activation requests, and…
  • POSTCreate role assignment schedule instance/roleManagement/directory/roleAssignmentScheduleInstances
  • GETList role eligibility schedule requests/roleManagement/directory/roleEligibilityScheduleRequestsIn PIM, retrieve the requests for role eligibilities for principals made through the unifiedRoleEligibilityScheduleRequest object.
  • POSTCreate role eligibility schedule request/roleManagement/directory/roleEligibilityScheduleRequestsIn PIM, request for a role eligibility for a principal through the unifiedRoleEligibilityScheduleRequest object. This operation allows both admins and…
  • GETList role eligibility schedule instances/roleManagement/directory/roleEligibilityScheduleInstancesGet the instances of role eligibilities.
  • POSTCreate role eligibility schedule instance/roleManagement/directory/roleEligibilityScheduleInstances
  • GETList role definitions/roleManagement/directory/deletedItems/roleDefinitionsList custom unifiedRoleDefinition objects that have been soft-deleted from Microsoft Entra directory role management. Built-in role definitions can't be…
  • POSTCreate role definition/roleManagement/directory/deletedItems/roleDefinitions

Directory: tenant governance

  • GETGet tenant governance/directory/tenantGovernanceContainer for Microsoft Entra Tenant Governance capabilities.
  • DELETEDelete tenant governance/directory/tenantGovernance
  • PATCHUpdate tenant governance/directory/tenantGovernance
  • GETGet settings/directory/tenantGovernance/settingsRead the properties of the tenantGovernanceSetting singleton, which controls related tenant discovery and invitation capabilities.
  • DELETEDelete settings/directory/tenantGovernance/settings
  • PATCHUpdate settings/directory/tenantGovernance/settingsUpdate the canReceiveInvitations property of the tenantGovernanceSetting singleton. This property controls whether the tenant can receive governance…
  • GETList related tenants/directory/tenantGovernance/relatedTenantsGet a list of relatedTenant objects and their properties, including relationship metrics.
  • POSTCreate related tenant/directory/tenantGovernance/relatedTenants
  • GETList governance requests/directory/tenantGovernance/governanceRequestsGet a list of the governanceRequest objects and their properties. This API method returns all governance requests where the calling tenant is either the…
  • POSTCreate governance request/directory/tenantGovernance/governanceRequestsCreate a new governanceRequest to establish a governance relationship with a governed tenant. The governed tenant can then accept or reject the request.
  • GETList governance invitations/directory/tenantGovernance/governanceInvitationsGet a list of the governanceInvitation objects and their properties. This API method returns all governance invitations where the calling tenant is either the…
  • POSTCreate governance invitation/directory/tenantGovernance/governanceInvitationsCreate a new governanceInvitation to establish a governance relationship with a governed tenant. Invitations provide an alternative mechanism to governance…
  • GETList governance relationships/directory/tenantGovernance/governanceRelationshipsGet a list of the governanceRelationship objects and their properties. This API method returns all governance relationships where the calling tenant is either…
  • POSTCreate governance relationship/directory/tenantGovernance/governanceRelationships
  • GETList governance policy templates/directory/tenantGovernance/governancePolicyTemplatesGet a list of the tenantGovernancePolicyTemplate objects and their properties. Policy templates define the configuration that is applied when establishing…
  • POSTCreate governance policy template/directory/tenantGovernance/governancePolicyTemplatesCreate a new tenantGovernancePolicyTemplate that defines the configuration for establishing governance relationships, including role assignments and…
  • POSTCreate refresh/directory/tenantGovernance/relatedTenants/refreshRefresh the list of related tenants. The list is also automatically refreshed daily.
  • POSTCreate enable related tenant/directory/tenantGovernance/settings/enableRelatedTenantsEnable the related tenants feature for tenant discovery. After calling this action, the isRelatedTenantsEnabled property of tenantGovernanceSetting is set to…
  • GETRefresh status (related tenant)/directory/tenantGovernance/relatedTenants/refreshStatus()Get the status of the most recent related tenants refresh operation.

Directory: remote tenant groups

  • GETList remote tenant groups/directory/remoteTenantGroupsDeprecated. Get a list of the remoteTenantGroup objects and their properties.
  • POSTCreate remote tenant group/directory/remoteTenantGroupsDeprecated.
  • GETGet remote tenant group/directory/remoteTenantGroups/:remoteTenantGroup-idDeprecated. Read the properties and relationships of a remoteTenantGroup object.
  • DELETEDelete remote tenant group/directory/remoteTenantGroups/:remoteTenantGroup-idDeprecated.
  • PATCHUpdate remote tenant group/directory/remoteTenantGroups/:remoteTenantGroup-idDeprecated.

Directory: administrative units

  • GETList administrative units/directory/administrativeUnitsRetrieve a list of administrativeUnit objects.
  • POSTCreate administrative unit/directory/administrativeUnitsCreate a new administrativeUnit.
  • GETTrack changes to administrative units (delta)/directory/administrativeUnits/delta()
  • GETGet administrative unit/directory/administrativeUnits/:administrativeUnit-idRetrieve the properties and relationships of an administrativeUnit object. The administrativeUnit resource supports extensions, which also allows you to use…
  • DELETEDelete administrative unit/directory/administrativeUnits/:administrativeUnit-idDelete an administrativeUnit.
  • PATCHUpdate administrative unit/directory/administrativeUnits/:administrativeUnit-idUpdate the properties of an administrativeUnit object.

Directory: device local credentials

  • GETList device local credentials/directory/deviceLocalCredentialsGet a list of the deviceLocalCredentialInfo objects and their properties, excluding the credentials property.
  • POSTCreate device local credential/directory/deviceLocalCredentials
  • GETGet device local credential/directory/deviceLocalCredentials/:deviceLocalCredentialInfo-idRetrieve the properties of a deviceLocalCredentialInfo for a specified device object.
  • DELETEDelete device local credential/directory/deviceLocalCredentials/:deviceLocalCredentialInfo-id
  • PATCHUpdate device local credential/directory/deviceLocalCredentials/:deviceLocalCredentialInfo-id

Directory: public key infrastructure

  • GETGet public key infrastructure/directory/publicKeyInfrastructureThe collection of public key infrastructure instances for the certificate-based authentication feature for users in a Microsoft Entra tenant.
  • DELETEDelete public key infrastructure/directory/publicKeyInfrastructure
  • PATCHUpdate public key infrastructure/directory/publicKeyInfrastructure
  • GETList certificate based auth configurations/directory/publicKeyInfrastructure/certificateBasedAuthConfigurationsGet a list of the certificateBasedAuthPki objects and their properties.
  • POSTCreate certificate based auth configuration/directory/publicKeyInfrastructure/certificateBasedAuthConfigurationsCreate a new certificateBasedAuthPki object.

Directory: federation configurations

  • GETList federation configurations/directory/federationConfigurationsConfigure domain federation with organizations whose identity provider (IdP) supports either the SAML or WS-Fed protocol.
  • POSTCreate federation configuration/directory/federationConfigurations

Showing 300 of 400 endpoints. Fork the collection to see all of them.

API details

Base URL
https://graph.microsoft.com/v1.0
Authentication
OAuth 2.0 (authorization code, client credentials flows)
Operations
400 operations on 241 pathsGET 163POST 140DELETE 49PATCH 42PUT 6
5 marked deprecated
Main resources
Role management: directory 26Role management: entitlement management 26Organization: branding 23Devices 20Directory roles 19Directory: tenant governance 19Organization 19Contacts 18Domains 16Contracts 14
Description format
OpenAPI 3.0.4, API version v1.0

How to test the Microsoft Graph: Directory, organization and roles in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Microsoft Graph: Directory, organization and roles collection, without the publisher's secrets.
  3. Add your credentialsThis API uses OAuth 2.0 (authorization code, client credentials flows). Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “List devices” (GET /devices), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Microsoft Graph: Directory, organization and roles?

Read the tenant (organization), domains, subscribed licences, directory roles and role management, devices, deleted items, schema extensions and guest… It is listed under Identity & security and has 400 endpoints.

Who publishes the Microsoft Graph: Directory, organization and roles?

It is listed from Microsoft's public API description (an OpenAPI document), not published by Microsoft on Swastik Codes. Anyone who controls microsoft.com can claim the profile by adding a DNS TXT record.

What is the base URL of the Microsoft Graph: Directory, organization and roles?

Requests go to https://graph.microsoft.com/v1.0. Endpoint paths are added to this base URL.

How do I authenticate with the Microsoft Graph: Directory, organization and roles?

With OAuth 2.0 (authorization code, client credentials flows).

How many endpoints does the Microsoft Graph: Directory, organization and roles have?

400 operations on 241 paths (163 GET, 140 POST, 49 DELETE, 42 PATCH, 6 PUT). The largest groups are Role management: directory, Role management: entitlement management, Organization: branding, Devices.

Is forking the Microsoft Graph: Directory, organization and roles free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.