Manage groups in Microsoft Graph

Article
2025-04-30

Groups in Microsoft Graph are containers for principals like users, devices, or applications that share access to resources. They make access management easier by grouping principals instead of managing them individually.

The group resource type in Microsoft Graph provides APIs to create and manage supported group types and their functionalities.

Note

You can only create groups using work or school accounts. Personal Microsoft accounts don't support groups.
All group-related operations in Microsoft Graph need administrator consent.

Types of groups supported in Microsoft Graph

Microsoft Graph supports these types of groups:

Microsoft 365 Groups
Security groups
Mail-enabled security groups
Distribution groups

Note

Dynamic distribution groups aren't supported in Microsoft Graph.

The following table shows how to identify types of groups using their properties and whether they can be managed through the Microsoft Graph groups API. The core differentiators are the values in the groupTypes, mailEnabled, and securityEnabled properties of a group.

Type	groupTypes	mailEnabled	securityEnabled	Managed via Microsoft Graph
Microsoft 365 Groups	`["Unified"]`	`true`	`true` or `false`	Yes
Security groups	`[]`	`false`	`true`	Yes
Mail-enabled security groups	`[]`	`true`	`true`	No (read-only)
Distribution groups	`[]`	`true`	`false`	No (read-only)

For more information, see Compare groups in Microsoft Entra ID.

Microsoft 365 Groups

Microsoft 365 Groups are designed for collaboration and provide access to shared resources like:

Outlook conversations and calendar.
SharePoint files and team site.
OneNote notebook.
Planner plans.
Intune device management.

Here's an example of a Microsoft 365 group in JSON format:

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

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups/$entity",
    "id": "4c5ee71b-e6a5-4343-9e2c-4244bc7e0938",
    "displayName": "OutlookGroup101",
    "groupTypes": ["Unified"],
    "mailEnabled": true,
    "securityEnabled": false,
    "mail": "[email protected]",
    "visibility": "Public"
}

To learn more about Microsoft 365 Groups, see Overview of Microsoft 365 Groups in Microsoft Graph.

Security groups and mail-enabled security groups

Security groups control access to resources. They can include users, other groups, devices, and service principals.

Mail-enabled security groups function like security groups but also allow email communication. These groups are read-only in Microsoft Graph. For more information, see Manage mail-enabled security groups.

Example of a security group in JSON format:

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

{
    "@odata.type": "#microsoft.graph.group",
    "id": "f87faa71-57a8-4c14-91f0-517f54645106",
    "displayName": "SecurityGroup101",
    "groupTypes": [],
    "mailEnabled": false,
    "securityEnabled": true
}

Group membership

Groups can have static or dynamic memberships. Dynamic membership uses rules to automatically add or remove members based on their properties. Not all object types can be members of Microsoft 365 and security groups.

The following table shows the types of members that can be added to either security groups or Microsoft 365 groups.

Object type	Member of security group	Member of Microsoft 365 group
User
Security group
Microsoft 365 group
Device
Service principal
Organizational contact

Dynamic membership

Dynamic membership means principals are added or removed from the group based on their properties. For example, a group can be set to include all users in the "Marketing" department. When a user is added to that department, they're automatically added to the group. Similarly, if a user leaves the department, they're removed from the group.

Only users and devices can be members of a dynamic group. Dynamic membership requires a Microsoft Entra ID P1 license for each unique user in a dynamic group.

The membership rule is defined using the Microsoft Entra ID dynamic group rule syntax.

Example of a dynamic membership rule:

"membershipRule": "user.department -eq \"Marketing\""

Dynamic membership requires the "DynamicMembership" value in the groupTypes property. The dynamic membership rule can be turned on or off through the membershipRuleProcessingState property. You can update a group from static membership to dynamic membership.

Example request to create a dynamic Microsoft 365 group:

POST https://graph.microsoft.com/v1.0/groups
Content-type: application/json

{
    "description": "Marketing department folks",
    "displayName": "Marketing department",
    "groupTypes": [
        "Unified",
        "DynamicMembership"
    ],
    "mailEnabled": true,
    "mailNickname": "marketing",
    "securityEnabled": false,
    "membershipRule": "user.department -eq \"Marketing\"",
    "membershipRuleProcessingState": "on"
}


// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new Group
{
	Description = "Marketing department folks",
	DisplayName = "Marketing department",
	GroupTypes = new List<string>
	{
		"Unified",
		"DynamicMembership",
	},
	MailEnabled = true,
	MailNickname = "marketing",
	SecurityEnabled = false,
	MembershipRule = "user.department -eq \"Marketing\"",
	MembershipRuleProcessingState = "on",
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups.PostAsync(requestBody);

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.



mgc groups create --body '{\
    "description": "Marketing department folks",\
    "displayName": "Marketing department",\
    "groupTypes": [\
        "Unified",\
        "DynamicMembership"\
    ],\
    "mailEnabled": true,\
    "mailNickname": "marketing",\
    "securityEnabled": false,\
    "membershipRule": "user.department -eq \"Marketing\"",\
    "membershipRuleProcessingState": "on"\
}\
'

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

requestBody := graphmodels.NewGroup()
description := "Marketing department folks"
requestBody.SetDescription(&description) 
displayName := "Marketing department"
requestBody.SetDisplayName(&displayName) 
groupTypes := []string {
	"Unified",
	"DynamicMembership",
}
requestBody.SetGroupTypes(groupTypes)
mailEnabled := true
requestBody.SetMailEnabled(&mailEnabled) 
mailNickname := "marketing"
requestBody.SetMailNickname(&mailNickname) 
securityEnabled := false
requestBody.SetSecurityEnabled(&securityEnabled) 
membershipRule := "user.department -eq \"Marketing\""
requestBody.SetMembershipRule(&membershipRule) 
membershipRuleProcessingState := "on"
requestBody.SetMembershipRuleProcessingState(&membershipRuleProcessingState) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
groups, err := graphClient.Groups().Post(context.Background(), requestBody, nil)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

Group group = new Group();
group.setDescription("Marketing department folks");
group.setDisplayName("Marketing department");
LinkedList<String> groupTypes = new LinkedList<String>();
groupTypes.add("Unified");
groupTypes.add("DynamicMembership");
group.setGroupTypes(groupTypes);
group.setMailEnabled(true);
group.setMailNickname("marketing");
group.setSecurityEnabled(false);
group.setMembershipRule("user.department -eq \"Marketing\"");
group.setMembershipRuleProcessingState("on");
Group result = graphClient.groups().post(group);

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


const options = {
	authProvider,
};

const client = Client.init(options);

const group = {
    description: 'Marketing department folks',
    displayName: 'Marketing department',
    groupTypes: [
        'Unified',
        'DynamicMembership'
    ],
    mailEnabled: true,
    mailNickname: 'marketing',
    securityEnabled: false,
    membershipRule: 'user.department -eq \"Marketing\"',
    membershipRuleProcessingState: 'on'
};

await client.api('/groups')
	.post(group);

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\Group;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new Group();
$requestBody->setDescription('Marketing department folks');
$requestBody->setDisplayName('Marketing department');
$requestBody->setGroupTypes(['Unified', 'DynamicMembership', 	]);
$requestBody->setMailEnabled(true);
$requestBody->setMailNickname('marketing');
$requestBody->setSecurityEnabled(false);
$requestBody->setMembershipRule('user.department -eq \"Marketing\"');
$requestBody->setMembershipRuleProcessingState('on');

$result = $graphServiceClient->groups()->post($requestBody)->wait();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


Import-Module Microsoft.Graph.Groups

$params = @{
	description = "Marketing department folks"
	displayName = "Marketing department"
	groupTypes = @(
	"Unified"
"DynamicMembership"
)
mailEnabled = $true
mailNickname = "marketing"
securityEnabled = $false
membershipRule = "user.department -eq "Marketing""
membershipRuleProcessingState = "on"
}

New-MgGroup -BodyParameter $params

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.group import Group
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = Group(
	description = "Marketing department folks",
	display_name = "Marketing department",
	group_types = [
		"Unified",
		"DynamicMembership",
	],
	mail_enabled = True,
	mail_nickname = "marketing",
	security_enabled = False,
	membership_rule = "user.department -eq \"Marketing\"",
	membership_rule_processing_state = "on",
)

result = await graph_client.groups.post(request_body)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

The request returns a 201 Created response code and the newly created group object in the response body.

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": "6f7cd676-5445-47c4-9c2b-c47da4671da2",
    "createdDateTime": "2023-01-20T07:00:31Z",
    "description": "Marketing department folks",
    "displayName": "Marketing department",
    "groupTypes": [
        "Unified",
        "DynamicMembership"
    ],
    "mail": "[email protected]",
    "mailEnabled": true,
    "mailNickname": "marketing",
    "membershipRule": "user.department -eq \"Marketing\"",
    "membershipRuleProcessingState": "On"
}

Other group settings

You can configure other settings for groups, such as:

Setting	Applies to
Group expiration	Microsoft 365 Groups
Group settings	Microsoft 365 Groups
On-premises synchronization settings	Security and Microsoft 365 Groups

Group search limitations for guests in organizations

Apps can search for groups in an organization's directory by querying the /groups resource (for example, https://graph.microsoft.com/beta/groups). This capability is available to administrators and members, but not to guests.

Guests, depending on the permissions granted to the app, can view the profile of a specific group (for example, https://graph.microsoft.com/beta/group/fc06287e-d082-4aab-9d5e-d6fd0ed7c8bc). However, they can't perform queries on the /groups resource that return multiple results.

Members generally have broader access to group resources, while guests have restricted permissions, limiting their access to certain group features. For more information, see Compare member and guest default permissions.

With appropriate permissions, apps can access group profiles through navigation properties, such as /groups/{id}/members.

Group-based licensing

Group-based licensing allows you to assign one or more product licenses to a Microsoft Entra group. Group members, including any new members, automatically inherit the licenses. When members leave the group, their licenses are automatically removed. This feature is only available for security groups and Microsoft 365 Groups with securityEnabled set to true.

For more information, see What is group-based licensing in Microsoft Entra ID?.

Properties stored outside the main data store

Most group resource data is stored in Microsoft Entra ID, but some properties, such as autoSubscribeNewMembers and allowExternalSenders, are stored in Microsoft Exchange. These properties can't be included in the same Create or Update request body as other group properties.

Additionally, properties stored outside the main data store aren't supported for change tracking. Changes to these properties don't appear in delta query responses.

The following group properties are stored outside the main data store:
accessType, allowExternalSenders, autoSubscribeNewMembers, cloudLicensing, hideFromAddressLists, hideFromOutlookClients, isFavorite, isSubscribedByMail, unseenConversationsCount, unseenCount, unseenMessagesCount, membershipRuleProcessingStatus, isArchived.

Common use cases for the groups API

The Microsoft Graph groups API supports these common operations:

Use case	API operations
Create and manage groups	Create, list, update, and delete
Manage group membership	List members, add member, and remove member
Manage group ownership	List owners, add owner, and remove owner
Microsoft 365 group functionality	Manage conversations, calendar events, OneNote notebooks, and enable for Teams

Microsoft Entra roles for managing groups

To manage groups, the signed-in user must have the appropriate Microsoft Graph permissions and be assigned a supported Microsoft Entra role.

The least privileged roles for managing groups are:

Directory Writers
Groups Administrator
User Administrator

For more information, see Least privileged roles to manage groups.

Next step

Start working with groups

Share via

Manage groups in Microsoft Graph

Types of groups supported in Microsoft Graph

Microsoft 365 Groups

Security groups and mail-enabled security groups

Group membership

Dynamic membership

Other group settings

Group search limitations for guests in organizations

Group-based licensing

Properties stored outside the main data store

Common use cases for the groups API

Microsoft Entra roles for managing groups

Next step

Feedback

Additional resources