administrativeUnit resource type

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

An administrative unit provides a conceptual container for user, group, and device directory objects. Using administrative units, a company administrator can now delegate administrative responsibilities to manage the users, groups, and devices contained within or scoped to an administrative unit to a regional or departmental administrator. This resource is an open type that allows other properties to be passed in.

This resource supports using delta query to track incremental additions, deletions, and updates, by providing a delta function.

Let's look at an example. Imagine that Contoso Corp is made up of two divisions - a West Coast Division and an East Coast Division. Directory roles at Contoso are scoped to the entire tenant. Lee, a Contoso company administrator, wants to delegate administrative responsibilities, but scope them to the West Coast Division or the East Coast division. Lee can create a West Coast administrative unit and place all West Coast users into this administrative unit. Similarly, Lee can create an East Coast administrative unit. Now Lee, can start delegating administrative responsibilities to others, but scoped to the new administrative units he's created. Lee places Jennifer in a helpdesk administrator role scoped to the West Coast administrative unit. This allows Jennifer to reset any user's password, but only if those users are in the West Coast administrative unit. Similarly, Lee places Dave in a user account administrator role scoped to the East Coast administrative unit. This allows Dave to update users, assign licenses and reset any user's password, but only if those users are in the East Coast administrative unit. For a video overview, please see Introduction to Microsoft Entra Administrative Units.

This resource supports:

  • Adding your own data to custom properties as extensions.
  • Using delta query to track incremental additions, deletions, and updates, by providing a delta function.

Methods

Method Return Type Description
Create administrativeUnit Create a new administrative unit.
List administrativeUnit collection List properties of all administrativeUnits.
Get administrativeUnit Read properties and relationships of a specific administrativeUnit object.
Update administrativeUnit Update administrativeUnit object.
Delete None Delete administrativeUnit object.
Get delta administrativeUnit Get newly created, updated, or deleted administrativeUnits without having to perform a full read of the entire resource collection.
Add a member directoryObject Add a member (user or group).
List members directoryObject collection Get the list of (user and group) members.
Get a member directoryObject Get a specific member.
Remove a member directoryObject Remove a member.
Add a scopedRoleMember scopedRoleMembership Assign a Microsoft Entra role with administrative unit scope.
List scopedRoleMembers scopedRoleMembership collection List Microsoft Entra role assignments with administrative unit scope.
Get a scopedRoleMember scopedRoleMembership Get a Microsoft Entra role assignment with administrative unit scope.
Remove a scopedRoleMember scopedRoleMembership Remove a Microsoft Entra role assignment with administrative unit scope.
Open extensions
Create open extension openTypeExtension Create an open extension and add custom properties to a new or existing resource.
Get open extension openTypeExtension collection Get an open extension identified by the extension name.
Schema extensions
Add schema extension values Create a schema extension definition and then use it to add custom typed data to a resource.

Note

The URL endpoint for calling the administrativeUnits API is /administrativeUnits in the beta endpoint but /directory/administrativeUnits in the v1.0 endpoint.

Properties

Important

Specific usage of $filter and the $search query parameter is supported only when you use the ConsistencyLevel header set to eventual and $count. For more information, see Advanced query capabilities on directory objects.

Property Type Description
description String An optional description for the administrative unit. Supports $filter (eq, ne, in, startsWith), $search.
displayName String Display name for the administrative unit. Supports $filter (eq, ne, not, ge, le, in, startsWith, and eq on null values), $search, and $orderby.
id String Unique identifier for the administrative unit. Read-only. Supports $filter (eq).
isMemberManagementRestricted Boolean true if members of this administrative unit should be treated as sensitive, which requires specific permissions to manage. Default value is false. Use this property to define administrative units whose roles don't inherit from tenant-level administrators, and management of individual member objects is limited to administrators scoped to a restricted management administrative unit. Immutable, so can't be changed later.

For more information about working with restricted management administrative units, see Restricted management administrative units in Microsoft Entra ID.
membershipRule String Dynamic membership rule for the administrative unit. For more about the rules that you can use for dynamic administrative units and dynamic groups, see Using attributes to create advanced rules.
membershipRuleProcessingState String Used to control whether the dynamic membership rule is actively processed. Set to On when you want the dynamic membership rule to be active and Paused if you want to stop updating membership dynamically. If not set, the default behavior is Paused.
membershipType String Membership type for the administrative unit. Can be dynamic or assigned. If not set, the default behavior is assigned.
visibility String Controls whether the administrative unit and its members are hidden or public. Can be set to HiddenMembership or Public. If not set, the default behavior is Public. When set to HiddenMembership, only members of the administrative unit can list other members of the administrative unit.

Tip

Directory extensions and associated data are returned by default while schema extensions and associated data returned only on $select.

Relationships

Relationship Type Description
extensions extension collection The collection of open extensions defined for this administrative unit. Nullable.
members directoryObject collection Users and groups that are members of this administrative unit. Supports $expand.
scopedRoleMembers scopedRoleMembership collection Scoped-role members of this administrative unit.

JSON representation

Here's a JSON representation of the resource.

{
  "description": "String",
  "displayName": "String",
  "id": "String (identifier)",
  "visibility": "String",
  "membershipType": "String",
  "membershipRule": "String",
  "membershipRuleProcessingState": "String"
}