Skip to content

administrativeunit-post-members.md

Latest commit

 

History

History
271 lines (216 loc) · 12.2 KB

administrativeunit-post-members.md

File metadata and controls

271 lines (216 loc) · 12.2 KB
title Add a member
description Use this API to add a member (user, group, or device) to an administrative unit.
author DougKirschner
ms.localizationpriority medium
ms.subservice entra-directory-management
doc_type apiPageType
ms.date 10/24/2024

Add a member

Namespace: microsoft.graph

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.

[!INCLUDE national-cloud-support]

Permissions

One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Permissions to add an existing user, group, or device

Permission type Permissions (from least to most privileged)
Delegated (work or school account) AdministrativeUnit.ReadWrite.All
Delegated (personal Microsoft account) Not supported.
Application AdministrativeUnit.ReadWrite.All

[!INCLUDE rbac-admin-units-apis-write]

Permissions to create a new group

Permission type Permissions (from least to most privileged)
Delegated (work or school account) Group.ReadWrite.All and AdministrativeUnit.Read.All, Directory.ReadWrite.All
Delegated (personal Microsoft account) Not supported.
Application Group.Create and AdministrativeUnit.Read.All, Group.ReadWrite.All and AdministrativeUnit.Read.All, Directory.ReadWrite.All

Important

To create a new group in an administrative unit, the calling principal must be assigned at least one of the following Microsoft Entra roles at the scope of the administrative unit:

  • Groups Administrator
  • User Administrator

For app-only scenarios - apart from these roles, the service principal requires additional permissions to read the directory. These permissions can be granted via assignment of supported Microsoft Entra roles, such the Directory Readers role; or they can be granted via Microsoft Graph application permissions that allow reading the directory, such as Directory.Read.All.

HTTP request

The following request adds an existing user, group, or device to the administrative unit.

POST /directory/administrativeUnits/{id}/members/$ref

The following request creates a new group within the administrative unit.

POST /directory/administrativeUnits/{id}/members

Request headers

Name Description
Authorization Bearer {token}. Required. Learn more about authentication and authorization.
Content-type application/json. Required.

Request body

Adding an existing user, group, or device

In the request body, provide the ID of a user, group, device, or directoryObject to be added. If the administrative unit is a restricted management administrative unit ("isMemberManagementRestricted": true), the group type must be a Microsoft Entra security group. Only nonunified groups that are security-enabled, not mail-enabled, and not on-premises sync-enabled are supported.

Creating a new group

The following table shows the properties of the group resource to specify when you create a group in the administrative unit.

Property Type Description
displayName string The name to display in the address book for the group. Required.
description string A description for the group. Optional.
isAssignableToRole Boolean Set to true to enable the group to be assigned to a Microsoft Entra role. Privileged Role Administrator is the least privileged role to set the value of this property. Optional.
mailEnabled Boolean Set to true for mail-enabled groups. Required.
mailNickname string The mail alias for the group. These characters can't be used in the mailNickName: @()\[]";:.<>,SPACE. Required.
securityEnabled Boolean Set to true for security-enabled groups, including Microsoft 365 groups. Required.
owners directoryObject collection This property represents the owners for the group at creation time. Optional.
members directoryObject collection This property represents the members for the group at creation time. Optional.
visibility String Specifies the visibility of a Microsoft 365 group. The possible values are: Private, Public, HiddenMembership, or empty (which is interpreted as Public).

Response

If successful, adding an existing object (using $ref) returns 204 No Content response code. It doesn't return anything in the response body.

When creating a new group (without $ref), this method returns a 201 Created response code and a group object in the response body. The response includes only the default properties of the group. You must supply the "@odata.type" : "#microsoft.graph.group" line in the request body to explicitly identify the new member as a group. A request body without the correct @odata.type returns a 400 Bad Request error message.

Examples

Example 1: Add an existing user or group

The following request adds an existing user or group to an administrative unit.

Request

The following example shows a request.

HTTP

POST https://graph.microsoft.com/v1.0/directory/administrativeUnits/{id}/members/$ref
Content-type: application/json

{
  "@odata.id":"https://graph.microsoft.com/v1.0/groups/{id}"
}

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

In the request body, provide the id of the user or group object you want to add.

Response

The following example shows the response.

HTTP/1.1 204 No Content

Example 2: Create a new group

The following example creates a new group in the administrative unit. You must supply the "@odata.type" : "#microsoft.graph.group" line in the request body to explicitly identify the new member as a group. A request body without the correct @odata.type returns a 400 Bad Request error message.

Request

The following example shows a request.

HTTP

POST https://graph.microsoft.com/v1.0/directory/administrativeUnits/{id}/members
Content-type: application/json

{
  "@odata.type": "#microsoft.graph.group",
  "description": "Self help community for golf",
  "displayName": "Golf Assist",
  "groupTypes": [
    "Unified"
  ],
  "mailEnabled": true,
  "mailNickname": "golfassist",
  "securityEnabled": false
}

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

In the request body, provide the properties of the group object you want to add.

Response

The following example shows the response.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 201 Created
Content-type: application/json

{
   "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups/$entity",
     "id": "45b7d2e7-b882-4a80-ba97-10b7a63b8fa4",
     "deletedDateTime": null,
     "classification": null,
     "createdDateTime": "2018-12-22T02:21:05Z",
     "description": "Self help community for golf",
     "displayName": "Golf Assist",
     "expirationDateTime": null,
     "groupTypes": [
         "Unified"
     ],
   "isAssignableToRole": null,
     "mail": "golfassist@contoso.com",
     "mailEnabled": true,
     "mailNickname": "golfassist",
     "membershipRule": null,
     "membershipRuleProcessingState": null,
     "onPremisesLastSyncDateTime": null,
     "onPremisesSecurityIdentifier": null,
     "onPremisesSyncEnabled": null,
     "preferredDataLocation": "CAN",
     "preferredLanguage": null,
     "proxyAddresses": [
         "SMTP:golfassist@contoso.com"
     ],
     "renewedDateTime": "2018-12-22T02:21:05Z",
     "resourceBehaviorOptions": [],
     "resourceProvisioningOptions": [],
     "securityEnabled": false,
     "securityIdentifier": "S-1-12-1-1753967289-1089268234-832641959-555555555",
     "theme": null,
     "visibility": "Public",
     "onPremisesProvisioningErrors": []
}