swagger: "2.0"
schemes:
  - https
host: management.azure.com
info:
  description: |
    The Azure Management Groups API enables consolidation of multiple 
    subscriptions/resources into an organizational hierarchy and centrally 
    manage access control, policies, alerting and reporting for those resources.
  title: Management Groups
  version: 2017-11-01-preview
  x-apisguru-categories:
    - cloud
  x-logo:
    url: https://api.apis.guru/v2/cache/logo/https_assets.onestore.ms_cdnfiles_onestorerolling-1606-01000_shell_v3_images_logo_microsoft.png
  x-origin:
    - format: swagger
      url: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/master/specification/managementgroups/resource-manager/Microsoft.Management/preview/2017-11-01-preview/management.json
      version: "2.0"
  x-preferred: false
  x-providerName: azure.com
  x-serviceName: managementgroups-management
  x-tags:
    - Azure
    - Microsoft
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  azure_auth:
    authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize
    description: Azure Active Directory OAuth2 Flow.
    flow: implicit
    scopes:
      user_impersonation: impersonate your user account
    type: oauth2
security:
  - azure_auth:
      - user_impersonation
parameters:
  ApiVersionParameter:
    description: Version of the API to be used with the client request. The current version is 2017-11-01-preview.
    in: query
    name: api-version
    required: true
    type: string
  CacheControlHeader:
    default: no-cache
    description: Indicates that the request shouldn't utilize any caches.
    in: header
    name: Cache-Control
    type: string
    x-ms-parameter-location: method
  CreateManagementGroupRequestParameter:
    description: Management group creation parameters.
    in: body
    name: createManagementGroupRequest
    required: true
    schema:
      $ref: "#/definitions/CreateManagementGroupRequest"
    x-ms-parameter-location: method
  ExpandParameter:
    description: The $expand=children query string parameter allows clients to request inclusion of children in the response payload.
    enum:
      - children
    in: query
    name: $expand
    required: false
    type: string
    x-ms-parameter-location: method
  GroupIdParameter:
    description: Management Group ID.
    in: path
    name: groupId
    required: true
    type: string
    x-ms-parameter-location: method
  RecurseParameter:
    description: The $recurse=true query string parameter allows clients to request inclusion of entire hierarchy in the response payload.
    in: query
    name: $recurse
    required: false
    type: boolean
    x-ms-parameter-location: method
  SubscriptionIdParameter:
    description: Subscription ID.
    in: path
    name: subscriptionId
    required: true
    type: string
    x-ms-parameter-location: method
tags:
  - description: |
      A Management Group is a customer defined scope (grouping mechanism) that 
      provides access control (authorization), policy management and reporting. 
      Management Groups are organized in a strictly tree-based hierarchy.
    name: ManagementGroups
  - description: |
      Management operations supported by the Microsoft.Management resource provider.
    name: Operations
paths:
  /providers/Microsoft.Management/managementGroups:
    get:
      description: |
        List management groups for the authenticated user.
      operationId: ManagementGroups_List
      parameters:
        - $ref: "#/parameters/ApiVersionParameter"
        - $ref: "#/parameters/CacheControlHeader"
        - description: |
            Page continuation token is only used if a previous operation returned a partial result. 
            If a previous response contains a nextLink element, the value of the nextLink element will include a token parameter that specifies a starting point to use for subsequent calls.
          in: query
          name: $skiptoken
          required: false
          type: string
      responses:
        "200":
          description: OK
          schema:
            $ref: "#/definitions/ManagementGroupListResult"
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
      tags:
        - ManagementGroups
      x-ms-examples:
        GetManagementGroups:
          parameters:
            api-version: 2017-11-01-preview
          responses:
            "200":
              body:
                value:
                  - id: /providers/Microsoft.Management/managementGroups/00000000-0000-0000-0000-000000000001
                    name: 00000000-0000-0000-0000-000000000001
                    properties:
                      displayName: Group Name 1
                      tenantId: 00000000-0000-0000-0000-000000000000
                    type: /providers/Microsoft.Management/managementGroups
                  - id: /providers/Microsoft.Management/managementGroups/00000000-0000-0000-0000-000000000002
                    name: 00000000-0000-0000-0000-000000000002
                    properties:
                      displayName: Group Name 2
                      tenantId: 00000000-0000-0000-0000-000000000000
                    type: /providers/Microsoft.Management/managementGroups
      x-ms-pageable:
        nextLinkName: nextLink
  "/providers/Microsoft.Management/managementGroups/{groupId}":
    delete:
      description: |
        Delete management group.
        If a management group contains child resources, the request will fail.
      operationId: ManagementGroups_Delete
      parameters:
        - $ref: "#/parameters/GroupIdParameter"
        - $ref: "#/parameters/ApiVersionParameter"
        - $ref: "#/parameters/CacheControlHeader"
      responses:
        "200":
          description: OK - management group deleted successfully
        "204":
          description: NoContent - management group does not exist
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
      tags:
        - ManagementGroups
      x-ms-examples:
        DeleteManagementGroup:
          parameters:
            api-version: 2017-11-01-preview
            groupId: 00000000-0000-0000-0000-000000000001
          responses:
            "200": {}
            "204": {}
    get:
      description: |
        Get the details of the management group.
      operationId: ManagementGroups_Get
      parameters:
        - $ref: "#/parameters/GroupIdParameter"
        - $ref: "#/parameters/ApiVersionParameter"
        - $ref: "#/parameters/ExpandParameter"
        - $ref: "#/parameters/RecurseParameter"
        - $ref: "#/parameters/CacheControlHeader"
      responses:
        "200":
          description: OK
          schema:
            $ref: "#/definitions/ManagementGroup"
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
      tags:
        - ManagementGroups
      x-ms-examples:
        GetManagementGroup:
          parameters:
            Cache-Control: no-cache
            api-version: 2018-01-01-preview
            groupId: 20000000-0001-0000-0000-000000000000
          responses:
            "200":
              body:
                id: /providers/Microsoft.Management/managementGroups/20000000-0001-0000-0000-000000000000
                name: 20000000-0001-0000-0000-000000000000
                properties:
                  children: null
                  details:
                    parent:
                      displayName: RootGroup
                      parentId: /providers/Microsoft.Management/managementGroups/RootGroup
                    updatedBy: 16b8ef21-5c9f-420c-bcc9-e4f8c9f30b4b
                    updatedTime: 2018-01-01T00:00:00.00Z
                    version: 1
                  displayName: Group 1 Tenant 2
                  tenantId: 20000000-0000-0000-0000-000000000000
                type: /providers/Microsoft.Management/managementGroups
        GetManagementGroupWithExpand:
          parameters:
            $expand: children
            Cache-Control: no-cache
            api-version: 2017-11-01-preview
            groupId: 00000000-0000-0000-0000-000000000001
          responses:
            "200":
              body:
                id: /providers/Microsoft.Management/managementGroups/00000000-0000-0000-0000-000000000001
                name: 00000000-0000-0000-0000-000000000001
                properties:
                  children:
                    - childId: /providers/Microsoft.Management/managementGroups/00000000-0000-0000-0000-000000000002
                      childType: ManagementGroup
                      displayName: Group Name 2
                    - childId: /providers/Microsoft.Management/managementGroups/00000000-0000-0000-0000-000000000003
                      childType: ManagementGroup
                      displayName: Group Name 3
                    - childId: /subscriptions/00000000-0000-0000-0000-000000000011
                      childType: Subscription
                      displayName: Subscription Name 1
                  details:
                    parent:
                      displayName: RootGroup
                      parentId: /providers/Microsoft.Management/managementGroups/RootGroup
                    updatedBy: Test
                    updatedTime: 2017-01-01T00:00:00Z
                    version: 1
                  displayName: Group Name 1
                  tenantId: 00000000-0000-0000-0000-000000000000
                type: /providers/Microsoft.Management/managementGroups
        GetManagementGroupsWithExpandAndRecurse:
          parameters:
            $expand: children
            $recurse: true
            Cache-Control: no-cache
            api-version: 2017-11-01-preview
            groupId: 00000000-0000-0000-0000-000000000001
          responses:
            "200":
              body:
                id: /providers/Microsoft.Management/managementGroups/00000000-0000-0000-0000-000000000001
                name: 00000000-0000-0000-0000-000000000001
                properties:
                  children:
                    - childId: /providers/Microsoft.Management/managementGroups/00000000-0000-0000-0000-000000000002
                      childType: ManagementGroup
                      children:
                        - childId: /providers/Microsoft.Management/managementGroups/00000000-0000-0000-0000-000000000004
                          childType: ManagementGroup
                          children:
                            - childId: /subscriptions/00000000-0000-0000-0000-000000000012
                              childType: Subscription
                              displayName: Subscription Name 2
                            - childId: /subscriptions/00000000-0000-0000-0000-000000000013
                              childType: Subscription
                              displayName: Subscription Name 3
                          displayName: Group Name 4
                      displayName: Group Name 2
                    - childId: /providers/Microsoft.Management/managementGroups/00000000-0000-0000-0000-000000000003
                      childType: ManagementGroup
                      children:
                        - childId: /subscriptions/00000000-0000-0000-0000-000000000014
                          childType: Subscription
                          displayName: Subscription Name 4
                      displayName: Group Name 3
                    - childId: /subscriptions/00000000-0000-0000-0000-000000000011
                      childType: Subscription
                      displayName: Subscription Name 1
                  details:
                    parent:
                      displayName: RootGroup
                      parentId: /providers/Microsoft.Management/managementGroups/RootGroup
                    updatedBy: Test
                    updatedTime: 2017-01-01T00:00:00Z
                    version: 1
                  displayName: Group Name 1
                  tenantId: 00000000-0000-0000-0000-000000000000
                type: /providers/Microsoft.Management/managementGroups
    patch:
      description: |
        Update a management group.
      operationId: ManagementGroups_Update
      parameters:
        - $ref: "#/parameters/GroupIdParameter"
        - $ref: "#/parameters/ApiVersionParameter"
        - $ref: "#/parameters/CreateManagementGroupRequestParameter"
        - $ref: "#/parameters/CacheControlHeader"
      responses:
        "200":
          description: OK
          schema:
            $ref: "#/definitions/ManagementGroup"
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
      tags:
        - ManagementGroups
      x-ms-examples:
        PatchManagementGroup:
          parameters:
            api-version: 2017-11-01-preview
            createManagementGroupRequest:
              "properties ":
                displayName: Group Name 2
                parentGroupId: /providers/Microsoft.Management/managementGroups/00000000-0000-0000-0000-000000000001
            groupId: 00000000-0000-0000-0000-000000000002
          responses:
            "200":
              body:
                id: /providers/Microsoft.Management/managementGroups/00000000-0000-0000-0000-000000000002
                name: 00000000-0000-0000-0000-000000000002
                properties:
                  details:
                    parent:
                      displayName: Group Name 1
                      parentId: /providers/Microsoft.Management/managementGroups/00000000-0000-0000-0000-000000000001
                    updatedBy: Test
                    updatedTime: 2017-01-01T00:00:00.00Z
                    version: 1
                  displayName: Group Name 2
                  tenantId: 00000000-0000-0000-0000-000000000000
                type: /providers/Microsoft.Management/managementGroups
    put:
      description: |
        Create or update a management group.
        If a management group is already created and a subsequent create request is issued with different properties, the management group properties will be updated.
      operationId: ManagementGroups_CreateOrUpdate
      parameters:
        - $ref: "#/parameters/GroupIdParameter"
        - $ref: "#/parameters/ApiVersionParameter"
        - $ref: "#/parameters/CreateManagementGroupRequestParameter"
        - $ref: "#/parameters/CacheControlHeader"
      responses:
        "200":
          description: OK
          schema:
            $ref: "#/definitions/ManagementGroup"
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
      tags:
        - ManagementGroups
      x-ms-examples:
        PutManagementGroup:
          parameters:
            api-version: 2017-11-01-preview
            createManagementGroupRequest:
              "properties ":
                displayName: Group Name 2
                parentGroupId: /providers/Microsoft.Management/managementGroups/00000000-0000-0000-0000-000000000001
            groupId: 00000000-0000-0000-0000-000000000002
          responses:
            "200":
              body:
                id: /providers/Microsoft.Management/managementGroups/00000000-0000-0000-0000-000000000002
                name: 00000000-0000-0000-0000-000000000002
                properties:
                  details:
                    parent:
                      displayName: Group Name 1
                      parentId: /providers/Microsoft.Management/managementGroups/00000000-0000-0000-0000-000000000001
                    updatedBy: Test
                    updatedTime: 2017-01-01T00:00:00.00Z
                    version: 1
                  displayName: Group Name 2
                  tenantId: 00000000-0000-0000-0000-000000000000
                type: /providers/Microsoft.Management/managementGroups
  "/providers/Microsoft.Management/managementGroups/{groupId}/subscriptions/{subscriptionId}":
    delete:
      description: |
        De-associates subscription from the management group.
      operationId: ManagementGroupSubscriptions_Delete
      parameters:
        - $ref: "#/parameters/GroupIdParameter"
        - $ref: "#/parameters/SubscriptionIdParameter"
        - $ref: "#/parameters/ApiVersionParameter"
        - $ref: "#/parameters/CacheControlHeader"
      responses:
        "204":
          description: No Content - subscription deleted successfully
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
      tags:
        - ManagementGroups
      x-ms-examples:
        DeleteSubscriptionFromManagementGroup:
          parameters:
            api-version: 2017-11-01-preview
            groupId: 00000000-0000-0000-0000-000000000001
            subscriptionId: 00000000-0000-0000-0000-000000000011
          responses:
            "204": {}
    put:
      description: |
        Associates existing subscription with the management group.
      operationId: ManagementGroupSubscriptions_Create
      parameters:
        - $ref: "#/parameters/GroupIdParameter"
        - $ref: "#/parameters/SubscriptionIdParameter"
        - $ref: "#/parameters/ApiVersionParameter"
        - $ref: "#/parameters/CacheControlHeader"
      responses:
        "204":
          description: No Content
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
      tags:
        - ManagementGroups
      x-ms-examples:
        AddSubscriptionToManagementGroup:
          parameters:
            api-version: 2017-11-01-preview
            groupId: 00000000-0000-0000-0000-000000000001
            subscriptionId: 00000000-0000-0000-0000-000000000011
          responses:
            "204": {}
  /providers/Microsoft.Management/operations:
    get:
      description: Lists all of the available Management REST API operations.
      operationId: Operations_List
      parameters:
        - $ref: "#/parameters/ApiVersionParameter"
      responses:
        "200":
          description: OK. The request has succeeded.
          schema:
            $ref: "#/definitions/OperationListResult"
        default:
          description: Error response describing why the operation failed.
          schema:
            $ref: "#/definitions/ErrorResponse"
      tags:
        - Operations
      x-ms-pageable:
        nextLinkName: nextLink
definitions:
  CreateManagementGroupRequest:
    description: Management group creation parameters.
    properties:
      displayName:
        description: The friendly name of the management group.
        type: string
      parentId:
        description: (Optional) The fully qualified ID for the parent management group.  For example, /providers/Microsoft.Management/managementGroups/0000000-0000-0000-0000-000000000000
        type: string
    type: object
  ErrorDetails:
    description: The details of the error.
    properties:
      code:
        description: One of a server-defined set of error codes.
        type: string
      message:
        description: A human-readable representation of the error.
        type: string
  ErrorResponse:
    description: The error object.
    properties:
      error:
        $ref: "#/definitions/ErrorDetails"
        title: Error
  ManagementGroup:
    description: The management group details.
    properties:
      id:
        description: The fully qualified ID for the management group.  For example, /providers/Microsoft.Management/managementGroups/0000000-0000-0000-0000-000000000000
        readOnly: true
        type: string
      name:
        description: The name of the management group. For example, 00000000-0000-0000-0000-000000000000
        readOnly: true
        type: string
      properties:
        $ref: "#/definitions/ManagementGroupProperties"
        title: Properties
        x-ms-client-flatten: true
      type:
        description: The type of the resource.  For example, /providers/Microsoft.Management/managementGroups
        readOnly: true
        type: string
    x-ms-azure-resource: true
  ManagementGroupChildInfo:
    description: The child information of a management group.
    properties:
      childId:
        description: The fully qualified ID for the child resource (management group or subscription).  For example, /providers/Microsoft.Management/managementGroups/0000000-0000-0000-0000-000000000000
        type: string
      childType:
        $ref: "#/definitions/ManagementGroupChildType"
        title: The type of child resource.
      children:
        description: The list of children.
        items:
          $ref: "#/definitions/ManagementGroupChildInfo"
        type: array
      displayName:
        description: The friendly name of the child resource.
        type: string
  ManagementGroupChildType:
    description: The type of child resource.
    enum:
      - ManagementGroup
      - Subscription
    type: string
  ManagementGroupDetails:
    description: The details of a management group.
    properties:
      parent:
        $ref: "#/definitions/ParentGroupInfo"
        title: Parent
      updatedBy:
        description: The identity of the principal or process that updated the object.
        type: string
      updatedTime:
        description: The date and time when this object was last updated.
        format: date-time
        type: string
      version:
        description: The version number of the object.
        format: int32
        type: number
    type: object
  ManagementGroupInfo:
    description: The management group resource.
    properties:
      id:
        description: The fully qualified ID for the management group.  For example, /providers/Microsoft.Management/managementGroups/0000000-0000-0000-0000-000000000000
        readOnly: true
        type: string
      name:
        description: The name of the management group. For example, 00000000-0000-0000-0000-000000000000
        readOnly: true
        type: string
      properties:
        $ref: "#/definitions/ManagementGroupInfoProperties"
        title: Properties
        x-ms-client-flatten: true
      type:
        description: The type of the resource. For example, /providers/Microsoft.Management/managementGroups
        readOnly: true
        type: string
  ManagementGroupInfoProperties:
    description: The generic properties of a management group.
    properties:
      displayName:
        description: The friendly name of the management group.
        type: string
      tenantId:
        description: The AAD Tenant ID associated with the management group. For example, 00000000-0000-0000-0000-000000000000
        type: string
    type: object
  ManagementGroupListResult:
    description: Describes the result of the request to list management groups.
    properties:
      nextLink:
        description: The URL to use for getting the next set of results.
        readOnly: true
        type: string
      value:
        description: The list of management groups.
        items:
          $ref: "#/definitions/ManagementGroupInfo"
        type: array
  ManagementGroupProperties:
    description: The generic properties of a management group.
    properties:
      children:
        description: The list of children.
        items:
          $ref: "#/definitions/ManagementGroupChildInfo"
        type: array
      details:
        $ref: "#/definitions/ManagementGroupDetails"
        title: Details
      displayName:
        description: The friendly name of the management group.
        type: string
      tenantId:
        description: The AAD Tenant ID associated with the management group. For example, 00000000-0000-0000-0000-000000000000
        type: string
    type: object
  Operation:
    description: Operation supported by the Microsoft.Management resource provider.
    properties:
      display:
        description: The object that represents the operation.
        properties:
          description:
            description: Operation description.
            readOnly: true
            type: string
          operation:
            description: The operation that can be performed.
            readOnly: true
            type: string
          provider:
            description: The name of the provider.
            readOnly: true
            type: string
          resource:
            description: The resource on which the operation is performed.
            readOnly: true
            type: string
      name:
        description: "Operation name: {provider}/{resource}/{operation}."
        readOnly: true
        type: string
    type: object
  OperationListResult:
    description: Describes the result of the request to list Microsoft.Management operations.
    properties:
      nextLink:
        description: URL to get the next set of operation list results if there are any.
        readOnly: true
        type: string
      value:
        description: List of operations supported by the Microsoft.Management resource provider.
        items:
          $ref: "#/definitions/Operation"
        readOnly: true
        type: array
  ParentGroupInfo:
    description: (Optional) The ID of the parent management group.
    properties:
      displayName:
        description: The friendly name of the parent management group.
        type: string
      parentId:
        description: The fully qualified ID for the parent management group.  For example, /providers/Microsoft.Management/managementGroups/0000000-0000-0000-0000-000000000000
        type: string
