Microsoft Azure Active Directory Groups API

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