openapi: 3.1.0 info: title: Microsoft Graph Identity Applications Groups API description: The Microsoft Graph Identity API provides a unified programmability model for managing Azure Active Directory (Microsoft Entra ID) resources including users, groups, applications, and service principals. This specification covers the core identity and access management endpoints available through the Microsoft Graph v1.0 REST API. version: 1.0.0 contact: name: Microsoft Graph Support url: https://developer.microsoft.com/en-us/graph email: graphdev@microsoft.com license: name: Microsoft API License url: https://learn.microsoft.com/en-us/legal/microsoft-apis/terms-of-use x-api-id: microsoft-graph-identity x-audience: external-public servers: - url: https://graph.microsoft.com/v1.0 description: Microsoft Graph v1.0 production endpoint - url: https://graph.microsoft.com/beta description: Microsoft Graph beta endpoint (preview features) security: - oauth2: - User.Read - User.ReadWrite.All - Directory.Read.All - Directory.ReadWrite.All tags: - name: Groups description: Manage groups in Azure Active Directory. Groups can be security groups, Microsoft 365 groups, or mail-enabled security groups. They provide shared access to resources for a collection of users and other directory objects. externalDocs: url: https://learn.microsoft.com/en-us/graph/api/resources/group?view=graph-rest-1.0 paths: /groups: get: operationId: listGroups summary: List Groups description: List all the groups in an organization, including Microsoft 365 groups, security groups, and mail-enabled security groups. Returns up to 100 objects by default. tags: - Groups parameters: - $ref: '#/components/parameters/top' - $ref: '#/components/parameters/skip' - $ref: '#/components/parameters/search' - $ref: '#/components/parameters/filter' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/orderby' - $ref: '#/components/parameters/select' - $ref: '#/components/parameters/expand' - $ref: '#/components/parameters/consistencyLevel' responses: '200': description: A collection of group objects. content: application/json: schema: type: object properties: '@odata.context': type: string '@odata.nextLink': type: string format: uri '@odata.count': type: integer value: type: array items: $ref: '#/components/schemas/Group' examples: Listgroups200Example: summary: Default listGroups 200 response x-microcks-default: true value: '@odata.context': example_value '@odata.nextLink': https://www.example.com '@odata.count': 10 value: - classification: example_value createdDateTime: '2026-01-15T10:30:00Z' description: A sample description. displayName: example_value expirationDateTime: '2026-01-15T10:30:00Z' groupTypes: - {} isAssignableToRole: example_value mail: example_value mailEnabled: true mailNickname: example_value membershipRule: example_value membershipRuleProcessingState: example_value onPremisesDomainName: example_value onPremisesLastSyncDateTime: '2026-01-15T10:30:00Z' onPremisesSyncEnabled: example_value preferredLanguage: example_value proxyAddresses: - {} renewedDateTime: '2026-01-15T10:30:00Z' securityEnabled: true securityIdentifier: example_value visibility: Public '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' security: - oauth2: - GroupMember.Read.All - Group.Read.All - Directory.Read.All externalDocs: url: https://learn.microsoft.com/en-us/graph/api/group-list?view=graph-rest-1.0 x-microcks-operation: delay: 0 dispatcher: FALLBACK post: operationId: createGroup summary: Create Group description: Create a new group. You can create a Microsoft 365 group, a security group, or a mail-enabled security group. The request body must include displayName, mailEnabled, mailNickname, and securityEnabled. tags: - Groups requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GroupCreate' examples: CreategroupRequestExample: summary: Default createGroup request x-microcks-default: true value: displayName: example_value description: A sample description. groupTypes: - example_value mailEnabled: true mailNickname: example_value securityEnabled: true visibility: Public isAssignableToRole: true members@odata.bind: - https://www.example.com owners@odata.bind: - https://www.example.com responses: '201': description: The created group object. content: application/json: schema: $ref: '#/components/schemas/Group' examples: Creategroup201Example: summary: Default createGroup 201 response x-microcks-default: true value: classification: example_value createdDateTime: '2026-01-15T10:30:00Z' description: A sample description. displayName: example_value expirationDateTime: '2026-01-15T10:30:00Z' groupTypes: - example_value isAssignableToRole: example_value mail: example_value mailEnabled: true mailNickname: example_value membershipRule: example_value membershipRuleProcessingState: example_value onPremisesDomainName: example_value onPremisesLastSyncDateTime: '2026-01-15T10:30:00Z' onPremisesSyncEnabled: example_value preferredLanguage: example_value proxyAddresses: - example_value renewedDateTime: '2026-01-15T10:30:00Z' securityEnabled: true securityIdentifier: example_value visibility: Public '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' security: - oauth2: - Group.ReadWrite.All - Directory.ReadWrite.All externalDocs: url: https://learn.microsoft.com/en-us/graph/api/group-post-groups?view=graph-rest-1.0 x-microcks-operation: delay: 0 dispatcher: FALLBACK /groups/{group-id}: get: operationId: getGroup summary: Get Group description: Get the properties and relationships of a group object. Returns a default set of properties unless $select is used. tags: - Groups parameters: - $ref: '#/components/parameters/groupId' - $ref: '#/components/parameters/select' - $ref: '#/components/parameters/expand' responses: '200': description: The requested group object. content: application/json: schema: $ref: '#/components/schemas/Group' examples: Getgroup200Example: summary: Default getGroup 200 response x-microcks-default: true value: classification: example_value createdDateTime: '2026-01-15T10:30:00Z' description: A sample description. displayName: example_value expirationDateTime: '2026-01-15T10:30:00Z' groupTypes: - example_value isAssignableToRole: example_value mail: example_value mailEnabled: true mailNickname: example_value membershipRule: example_value membershipRuleProcessingState: example_value onPremisesDomainName: example_value onPremisesLastSyncDateTime: '2026-01-15T10:30:00Z' onPremisesSyncEnabled: example_value preferredLanguage: example_value proxyAddresses: - example_value renewedDateTime: '2026-01-15T10:30:00Z' securityEnabled: true securityIdentifier: example_value visibility: Public '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' security: - oauth2: - GroupMember.Read.All - Group.Read.All - Directory.Read.All externalDocs: url: https://learn.microsoft.com/en-us/graph/api/group-get?view=graph-rest-1.0 x-microcks-operation: delay: 0 dispatcher: FALLBACK patch: operationId: updateGroup summary: Update Group description: Update the properties of a group object. Not all properties can be updated at the same time. tags: - Groups parameters: - $ref: '#/components/parameters/groupId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GroupUpdate' examples: UpdategroupRequestExample: summary: Default updateGroup request x-microcks-default: true value: displayName: example_value description: A sample description. mailNickname: example_value visibility: Public membershipRule: example_value membershipRuleProcessingState: 'On' preferredLanguage: example_value classification: example_value responses: '204': description: Group updated successfully. No content returned. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' security: - oauth2: - Group.ReadWrite.All - Directory.ReadWrite.All externalDocs: url: https://learn.microsoft.com/en-us/graph/api/group-update?view=graph-rest-1.0 x-microcks-operation: delay: 0 dispatcher: FALLBACK delete: operationId: deleteGroup summary: Delete Group description: Delete a group. When a Microsoft 365 group is deleted, it is moved to a temporary container and can be restored within 30 days. Security groups are permanently deleted immediately. tags: - Groups parameters: - $ref: '#/components/parameters/groupId' responses: '204': description: Group deleted successfully. No content returned. '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' security: - oauth2: - Group.ReadWrite.All - Directory.ReadWrite.All externalDocs: url: https://learn.microsoft.com/en-us/graph/api/group-delete?view=graph-rest-1.0 x-microcks-operation: delay: 0 dispatcher: FALLBACK /groups/{group-id}/members: get: operationId: listGroupMembers summary: List Group Members description: Get a list of the group's direct members. A group can have users, organizational contacts, devices, service principals, and other groups as members. tags: - Groups parameters: - $ref: '#/components/parameters/groupId' - $ref: '#/components/parameters/top' - $ref: '#/components/parameters/filter' - $ref: '#/components/parameters/select' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/consistencyLevel' responses: '200': description: A collection of directory objects that are members of the group. content: application/json: schema: type: object properties: '@odata.context': type: string value: type: array items: $ref: '#/components/schemas/DirectoryObject' examples: Listgroupmembers200Example: summary: Default listGroupMembers 200 response x-microcks-default: true value: '@odata.context': example_value value: - '@odata.type': example_value id: abc123 deletedDateTime: '2026-01-15T10:30:00Z' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' security: - oauth2: - GroupMember.Read.All - Group.Read.All - Directory.Read.All externalDocs: url: https://learn.microsoft.com/en-us/graph/api/group-list-members?view=graph-rest-1.0 x-microcks-operation: delay: 0 dispatcher: FALLBACK /groups/{group-id}/members/$ref: post: operationId: addGroupMember summary: Add Group Member description: Add a member to a group by posting a reference to the directory object. Users, service principals, groups, and organizational contacts can be added as members. tags: - Groups parameters: - $ref: '#/components/parameters/groupId' requestBody: required: true content: application/json: schema: type: object required: - '@odata.id' properties: '@odata.id': type: string format: uri description: The full URL of the directory object to add. For example, https://graph.microsoft.com/v1.0/directoryObjects/{id}. examples: - https://graph.microsoft.com/v1.0/directoryObjects/00000000-0000-0000-0000-000000000000 examples: AddgroupmemberRequestExample: summary: Default addGroupMember request x-microcks-default: true value: '@odata.id': https://www.example.com responses: '204': description: Member added successfully. No content returned. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' security: - oauth2: - GroupMember.ReadWrite.All - Group.ReadWrite.All - Directory.ReadWrite.All externalDocs: url: https://learn.microsoft.com/en-us/graph/api/group-post-members?view=graph-rest-1.0 x-microcks-operation: delay: 0 dispatcher: FALLBACK components: responses: Forbidden: description: Forbidden. The caller does not have sufficient permissions. content: application/json: schema: $ref: '#/components/schemas/ODataError' TooManyRequests: description: Too many requests. The client has been throttled. headers: Retry-After: description: Number of seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ODataError' NotFound: description: Not found. The specified resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ODataError' Unauthorized: description: Unauthorized. Authentication is required or the provided token is invalid. content: application/json: schema: $ref: '#/components/schemas/ODataError' BadRequest: description: Bad request. The request body or parameters are invalid. content: application/json: schema: $ref: '#/components/schemas/ODataError' parameters: select: name: $select in: query description: 'Selects specific properties to return. Comma-separated list of property names. Example: id,displayName,mail.' schema: type: string top: name: $top in: query description: Sets the page size of results. Maximum value depends on the API; defaults to 100 for most identity resources. schema: type: integer minimum: 1 maximum: 999 filter: name: $filter in: query description: Filters results using OData filter expressions. Supports eq, ne, not, in, startsWith, endsWith, and lambda operators. schema: type: string groupId: name: group-id in: path required: true description: The unique identifier (object ID) of the group. schema: type: string format: uuid count: name: $count in: query description: Includes a count of the total number of items in a collection alongside the page of data values. Requires ConsistencyLevel header. schema: type: boolean search: name: $search in: query description: Search items by search phrases. Requires ConsistencyLevel header set to eventual. Supports searching displayName and description. schema: type: string consistencyLevel: name: ConsistencyLevel in: header description: Indicates the requested consistency level. Required for advanced queries using $search, $filter with certain functions, or $count. Set to eventual. schema: type: string enum: - eventual skip: name: $skip in: query description: Skips the specified number of items in the result set. schema: type: integer minimum: 0 expand: name: $expand in: query description: Expands related entities inline. For example, expand members of a group or manager of a user. schema: type: string orderby: name: $orderby in: query description: 'Specifies the order of items returned. Use asc for ascending or desc for descending. Example: displayName asc.' schema: type: string schemas: DirectoryObject: type: object description: Represents an Azure Active Directory directory object. This is the base type for most directory resources. properties: '@odata.type': type: string description: The OData type of the directory object. example: example_value id: type: string format: uuid description: The unique identifier for the object. Globally unique across all directory objects. readOnly: true example: abc123 deletedDateTime: type: string format: date-time description: Date and time when this object was deleted. readOnly: true example: '2026-01-15T10:30:00Z' GroupCreate: type: object description: Properties required when creating a new group. required: - displayName - mailEnabled - mailNickname - securityEnabled properties: displayName: type: string description: The display name for the group. example: example_value description: type: string example: A sample description. groupTypes: type: array items: type: string description: Set to ["Unified"] for Microsoft 365 groups. Omit for security groups. example: [] mailEnabled: type: boolean example: true mailNickname: type: string example: example_value securityEnabled: type: boolean example: true visibility: type: string enum: - Public - Private - HiddenMembership example: Public isAssignableToRole: type: boolean example: true members@odata.bind: type: array items: type: string format: uri description: 'List of directory object URLs to add as members. Example: https://graph.microsoft.com/v1.0/directoryObjects/{id}' example: [] owners@odata.bind: type: array items: type: string format: uri description: List of directory object URLs to set as owners. example: [] Group: type: object description: 'Represents an Azure AD group. Groups are collections of principals with shared access to resources. Microsoft Graph supports several types of groups: Microsoft 365 groups, security groups, and mail-enabled security groups.' allOf: - $ref: '#/components/schemas/DirectoryObject' properties: classification: type: - string - 'null' description: Classification for the group (e.g., low, medium, high business impact). example: example_value createdDateTime: type: string format: date-time description: Timestamp of when the group was created. readOnly: true example: '2026-01-15T10:30:00Z' description: type: - string - 'null' description: An optional description for the group. example: A sample description. displayName: type: string description: The display name for the group. Required on creation. example: example_value expirationDateTime: type: - string - 'null' format: date-time description: Timestamp of when the group is set to expire. example: '2026-01-15T10:30:00Z' groupTypes: type: array items: type: string description: Specifies the group type. Include Unified for Microsoft 365 groups. Include DynamicMembership for dynamic groups. example: [] isAssignableToRole: type: - boolean - 'null' description: Indicates whether this group can be assigned to an Azure AD role. Can only be set at creation time. example: example_value mail: type: - string - 'null' format: email description: The SMTP address for the group. readOnly: true example: example_value mailEnabled: type: boolean description: Specifies whether the group is mail-enabled. Required on creation. example: true mailNickname: type: string description: The mail alias for the group, unique for Microsoft 365 groups. Required on creation. example: example_value membershipRule: type: - string - 'null' description: The rule that determines members for a dynamic group. example: example_value membershipRuleProcessingState: type: - string - 'null' description: Indicates whether the dynamic membership processing is on or paused. On or Paused. example: example_value onPremisesDomainName: type: - string - 'null' readOnly: true example: example_value onPremisesLastSyncDateTime: type: - string - 'null' format: date-time readOnly: true example: '2026-01-15T10:30:00Z' onPremisesSyncEnabled: type: - boolean - 'null' readOnly: true example: example_value preferredLanguage: type: - string - 'null' description: The preferred language for a Microsoft 365 group in ISO 639-1 format. example: example_value proxyAddresses: type: array items: type: string readOnly: true example: [] renewedDateTime: type: string format: date-time description: Timestamp of when the group was last renewed. readOnly: true example: '2026-01-15T10:30:00Z' securityEnabled: type: boolean description: Specifies whether the group is a security group. Required on creation. example: true securityIdentifier: type: - string - 'null' description: Security identifier (SID) of the group. readOnly: true example: example_value visibility: type: - string - 'null' description: Specifies the group join policy and group content visibility. Public, Private, or HiddenMembership. enum: - Public - Private - HiddenMembership example: Public ODataError: type: object description: OData error response from Microsoft Graph. properties: error: type: object properties: code: type: string description: Error code. message: type: string description: Error message. innerError: type: object properties: date: type: string format: date-time request-id: type: string format: uuid client-request-id: type: string format: uuid example: example_value GroupUpdate: type: object description: Properties that can be updated on an existing group. properties: displayName: type: string example: example_value description: type: string example: A sample description. mailNickname: type: string example: example_value visibility: type: string enum: - Public - Private - HiddenMembership example: Public membershipRule: type: string example: example_value membershipRuleProcessingState: type: string enum: - 'On' - Paused example: 'On' preferredLanguage: type: string example: example_value classification: type: string example: example_value securitySchemes: oauth2: type: oauth2 description: Microsoft identity platform OAuth 2.0 authorization. Supports authorization code flow, client credentials flow, and on-behalf-of flow. All API calls require a valid access token obtained from the Microsoft identity platform. flows: authorizationCode: authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token scopes: User.Read: Sign in and read user profile User.Read.All: Read all users' full profiles User.ReadWrite.All: Read and write all users' full profiles Group.Read.All: Read all groups Group.ReadWrite.All: Read and write all groups GroupMember.Read.All: Read group memberships GroupMember.ReadWrite.All: Read and write group memberships Application.Read.All: Read all applications Application.ReadWrite.All: Read and write all applications Directory.Read.All: Read directory data Directory.ReadWrite.All: Read and write directory data clientCredentials: tokenUrl: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token scopes: https://graph.microsoft.com/.default: Default scope for client credentials