Azure Policy Policy Definitions API

openapi: 3.2.0
info:
  title: Microsoft Azure Policy Policy Definitions API
  x-refined-note:
  - x-merged-from differs across the merged source definitions and was not carried
  - x-ownership differs across the merged source definitions and was not carried
  - x-source differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged PolicyDefinitions across 2 of this provider''s published API definitions: policyDefinitions.json, microsoft-azure-policy-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://management.azure.com
security:
- azure_auth:
  - user_impersonation
tags:
- name: PolicyDefinitions
paths:
  /subscriptions/{subscriptionId}/providers/Microsoft.Authorization/policyDefinitions/{policyDefinitionName}:
    put:
      tags:
      - PolicyDefinitions
      operationId: PolicyDefinitions_CreateOrUpdate
      summary: Creates or updates a policy definition in a subscription
      description: This operation creates or updates a policy definition in the given subscription with the given name.
      x-ms-examples:
        Create or update a policy definition:
          $ref: ./examples/createOrUpdatePolicyDefinition.json
        Create or update a policy definition with advanced parameters:
          $ref: ./examples/createOrUpdatePolicyDefinitionAdvancedParams.json
      parameters:
      - $ref: ../../../../../../common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter
      - name: policyDefinitionName
        in: path
        required: true
        description: The name of the policy definition to create.
        schema:
          type: string
          pattern: ^[^<>%&:\?/]*[^<>%&:\?/ ]+$
      - $ref: ../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      responses:
        '201':
          description: Created - Returns information about the policy definition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyDefinition'
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolicyDefinition'
        description: The policy definition properties.
        required: true
    delete:
      tags:
      - PolicyDefinitions
      operationId: PolicyDefinitions_Delete
      summary: Deletes a policy definition in a subscription
      description: This operation deletes the policy definition in the given subscription with the given name.
      x-ms-examples:
        Delete a policy definition:
          $ref: ./examples/deletePolicyDefinition.json
      parameters:
      - $ref: ../../../../../../common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter
      - name: policyDefinitionName
        in: path
        required: true
        description: The name of the policy definition to delete.
        schema:
          type: string
          pattern: ^[^<>%&:\?/]*[^<>%&:\?/ ]+$
      - $ref: ../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      responses:
        '204':
          description: No Content
        '200':
          description: OK
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
    get:
      tags:
      - PolicyDefinitions
      operationId: PolicyDefinitions_Get
      summary: Retrieves a policy definition in a subscription
      description: This operation retrieves the policy definition in the given subscription with the given name.
      x-ms-examples:
        Retrieve a policy definition:
          $ref: ./examples/getPolicyDefinition.json
      parameters:
      - $ref: ../../../../../../common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter
      - name: policyDefinitionName
        in: path
        required: true
        description: The name of the policy definition to get.
        schema:
          type: string
          pattern: ^[^<>%&:\?/]*[^<>%&:\?/ ]+$
      - $ref: ../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      responses:
        '200':
          description: OK - Returns information about the policy definition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyDefinition'
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
    servers:
    - url: https://management.azure.com
  /providers/Microsoft.Authorization/policyDefinitions/{policyDefinitionName}:
    get:
      tags:
      - PolicyDefinitions
      operationId: PolicyDefinitions_GetBuiltIn
      summary: Retrieves a built-in policy definition
      description: This operation retrieves the built-in policy definition with the given name.
      x-ms-examples:
        Retrieve a built-in policy definition:
          $ref: ./examples/getBuiltinPolicyDefinition.json
      parameters:
      - name: policyDefinitionName
        in: path
        required: true
        description: The name of the built-in policy definition to get.
        schema:
          type: string
          pattern: ^[^<>%&:\?/]*[^<>%&:\?/ ]+$
      - $ref: ../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      responses:
        '200':
          description: OK - Returns information about the built-in policy definition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyDefinition'
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
    servers:
    - url: https://management.azure.com
  ? /providers/Microsoft.Management/managementGroups/{managementGroupId}/providers/Microsoft.Authorization/policyDefinitions/{policyDefinitionName}
  : put:
      tags:
      - PolicyDefinitions
      operationId: PolicyDefinitions_CreateOrUpdateAtManagementGroup
      summary: Creates or updates a policy definition in a management group
      description: This operation creates or updates a policy definition in the given management group with the given name.
      x-ms-examples:
        Create or update a policy definition at management group level:
          $ref: ./examples/createOrUpdatePolicyDefinitionAtManagementGroup.json
      parameters:
      - $ref: '#/components/parameters/ManagementGroupIdParameter'
      - name: policyDefinitionName
        in: path
        required: true
        description: The name of the policy definition to create.
        schema:
          type: string
          pattern: ^[^<>%&:\?/]*[^<>%&:\?/ ]+$
      - $ref: ../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      responses:
        '201':
          description: Created - Returns information about the policy definition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyDefinition'
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolicyDefinition'
        description: The policy definition properties.
        required: true
    delete:
      tags:
      - PolicyDefinitions
      operationId: PolicyDefinitions_DeleteAtManagementGroup
      summary: Deletes a policy definition in a management group
      description: This operation deletes the policy definition in the given management group with the given name.
      x-ms-examples:
        Delete a policy definition at management group level:
          $ref: ./examples/deletePolicyDefinitionAtManagementGroup.json
      parameters:
      - $ref: '#/components/parameters/ManagementGroupIdParameter'
      - name: policyDefinitionName
        in: path
        required: true
        description: The name of the policy definition to delete.
        schema:
          type: string
          pattern: ^[^<>%&:\?/]*[^<>%&:\?/ ]+$
      - $ref: ../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      responses:
        '204':
          description: No Content
        '200':
          description: OK
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
    get:
      tags:
      - PolicyDefinitions
      operationId: PolicyDefinitions_GetAtManagementGroup
      summary: Retrieve a policy definition in a management group
      description: This operation retrieves the policy definition in the given management group with the given name.
      x-ms-examples:
        Retrieve a policy definition at management group level:
          $ref: ./examples/getPolicyDefinitionAtManagementGroup.json
      parameters:
      - $ref: '#/components/parameters/ManagementGroupIdParameter'
      - name: policyDefinitionName
        in: path
        required: true
        description: The name of the policy definition to get.
        schema:
          type: string
          pattern: ^[^<>%&:\?/]*[^<>%&:\?/ ]+$
      - $ref: ../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      responses:
        '200':
          description: OK - Returns information about the policy definition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyDefinition'
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
    servers:
    - url: https://management.azure.com
  /subscriptions/{subscriptionId}/providers/Microsoft.Authorization/policyDefinitions:
    get:
      tags:
      - PolicyDefinitions
      operationId: PolicyDefinitions_List
      summary: Retrieves policy definitions in a subscription
      description: 'This operation retrieves a list of all the policy definitions in a given subscription that match the optional given $filter. Valid values for $filter are: ''atExactScope()'', ''policyType -eq {value}'' or ''category eq ''{value}''''. If $filter is not provided, the unfiltered list includes all policy definitions associated with the subscription, including those that apply directly or from management groups that contain the given subscription. If $filter=atExactScope() is provided, the returned list only includes all policy definitions that at the given subscription. If $filter=''policyType -eq {value}'' is provided, the returned list only includes all policy definitions whose type match the {value}. Possible policyType values are NotSpecified, BuiltIn, Custom, and Static. If $filter=''category -eq {value}'' is provided, the returned list only includes all policy definitions whose category match the {value}.'
      x-ms-examples:
        List policy definitions by subscription:
          $ref: ./examples/listPolicyDefinitions.json
      parameters:
      - $ref: ../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      - $ref: ../../../../../../common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter
      - $ref: '#/components/parameters/PolicyDefinitionsFilterParameter'
      - $ref: '#/components/parameters/TopParameter'
      responses:
        '200':
          description: OK - Returns an array of policy definitions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyDefinitionListResult'
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      x-ms-pageable:
        nextLinkName: nextLink
    servers:
    - url: https://management.azure.com
  /providers/Microsoft.Authorization/policyDefinitions:
    get:
      tags:
      - PolicyDefinitions
      operationId: PolicyDefinitions_ListBuiltIn
      summary: Retrieve built-in policy definitions
      description: This operation retrieves a list of all the built-in policy definitions that match the optional given $filter. If $filter='policyType -eq {value}' is provided, the returned list only includes all built-in policy definitions whose type match the {value}. Possible policyType values are NotSpecified, BuiltIn, Custom, and Static. If $filter='category -eq {value}' is provided, the returned list only includes all built-in policy definitions whose category match the {value}.
      x-ms-examples:
        List built-in policy definitions:
          $ref: ./examples/listBuiltInPolicyDefinitions.json
      parameters:
      - $ref: ../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      - $ref: '#/components/parameters/PolicyDefinitionsFilterParameter'
      - $ref: '#/components/parameters/TopParameter'
      responses:
        '200':
          description: OK - Returns an array of built-in policy definitions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyDefinitionListResult'
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      x-ms-pageable:
        nextLinkName: nextLink
    servers:
    - url: https://management.azure.com
  /providers/Microsoft.Management/managementGroups/{managementGroupId}/providers/Microsoft.Authorization/policyDefinitions:
    get:
      tags:
      - PolicyDefinitions
      operationId: PolicyDefinitions_ListByManagementGroup
      summary: Retrieve policy definitions in a management group
      description: 'This operation retrieves a list of all the policy definitions in a given management group that match the optional given $filter. Valid values for $filter are: ''atExactScope()'', ''policyType -eq {value}'' or ''category eq ''{value}''''. If $filter is not provided, the unfiltered list includes all policy definitions associated with the management group, including those that apply directly or from management groups that contain the given management group. If $filter=atExactScope() is provided, the returned list only includes all policy definitions that at the given management group. If $filter=''policyType -eq {value}'' is provided, the returned list only includes all policy definitions whose type match the {value}. Possible policyType values are NotSpecified, BuiltIn, Custom, and Static. If $filter=''category -eq {value}'' is provided, the returned list only includes all policy definitions whose category match the {value}.'
      x-ms-examples:
        List policy definitions by management group:
          $ref: ./examples/listPolicyDefinitionsByManagementGroup.json
      parameters:
      - $ref: ../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      - $ref: '#/components/parameters/ManagementGroupIdParameter'
      - $ref: '#/components/parameters/PolicyDefinitionsFilterParameter'
      - $ref: '#/components/parameters/TopParameter'
      responses:
        '200':
          description: OK - Returns an array of policy definitions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyDefinitionListResult'
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      x-ms-pageable:
        nextLinkName: nextLink
    servers:
    - url: https://management.azure.com
components:
  schemas:
    ParameterDefinitionsValue:
      type: object
      properties:
        type:
          description: The data type of the parameter.
          type: string
          enum:
          - String
          - Array
          - Object
          - Boolean
          - Integer
          - Float
          - DateTime
          x-ms-enum:
            name: parameterType
            modelAsString: true
        allowedValues:
          type: array
          items:
            description: The collection of allowed values for the parameter.
          x-ms-identifiers: []
          description: The allowed values for the parameter.
        defaultValue:
          description: The default value for the parameter if no value is provided.
        schema:
          type: object
          description: Provides validation of parameter inputs during assignment using a self-defined JSON schema. This property is only supported for object-type parameters and follows the Json.NET Schema 2019-09 implementation. You can learn more about using schemas at https://json-schema.org/ and test draft schemas at https://www.jsonschemavalidator.net/.
        metadata:
          type: object
          properties:
            displayName:
              type: string
              description: The display name for the parameter.
            description:
              type: string
              description: The description of the parameter.
            strongType:
              type: string
              description: Used when assigning the policy definition through the portal. Provides a context aware list of values for the user to choose from.
            assignPermissions:
              type: boolean
              description: Set to true to have Azure portal create role assignments on the resource ID or resource scope value of this parameter during policy assignment. This property is useful in case you wish to assign permissions outside the assignment scope.
          additionalProperties:
            type: object
          description: General metadata for the parameter.
      description: The definition of a parameter that can be provided to the policy.
    ParameterDefinitions:
      description: The parameter definitions for parameters used in the policy. The keys are the parameter names.
      type: object
      additionalProperties:
        $ref: '#/components/schemas/ParameterDefinitionsValue'
    PolicyDefinitionListResult:
      type: object
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/PolicyDefinition'
          description: An array of policy definitions.
        nextLink:
          type: string
          description: The URL to use for getting the next set of results.
      description: List of policy definitions.
    PolicyDefinition:
      type: object
      properties:
        properties:
          x-ms-client-flatten: true
          $ref: '#/components/schemas/PolicyDefinitionProperties'
          description: The policy definition properties.
        id:
          readOnly: true
          type: string
          description: The ID of the policy definition.
        name:
          readOnly: true
          type: string
          description: The name of the policy definition.
        type:
          readOnly: true
          type: string
          description: The type of the resource (Microsoft.Authorization/policyDefinitions).
        systemData:
          $ref: ../../../../../../common-types/resource-management/v5/types.json#/definitions/systemData
          readOnly: true
          description: The system metadata relating to this resource.
      description: The policy definition.
      x-ms-azure-resource: true
    CloudError:
      type: object
      x-ms-external: true
      properties:
        error:
          $ref: ../../../../../../common-types/resource-management/v1/types.json#/definitions/ErrorResponse
      description: An error response from a policy operation.
    PolicyDefinitionProperties:
      type: object
      properties:
        policyType:
          type: string
          description: The type of policy definition. Possible values are NotSpecified, BuiltIn, Custom, and Static.
          enum:
          - NotSpecified
          - BuiltIn
          - Custom
          - Static
          x-ms-enum:
            name: policyType
            modelAsString: true
        mode:
          type: string
          description: The policy definition mode. Some examples are All, Indexed, Microsoft.KeyVault.Data.
          default: Indexed
        displayName:
          type: string
          description: The display name of the policy definition.
        description:
          type: string
          description: The policy definition description.
        policyRule:
          type: object
          description: The policy rule.
        metadata:
          type: object
          description: The policy definition metadata.  Metadata is an open ended object and is typically a collection of key value pairs.
        parameters:
          description: The parameter definitions for parameters used in the policy rule. The keys are the parameter names.
          $ref: '#/components/schemas/ParameterDefinitions'
        version:
          type: string
          description: 'The policy definition version in #.#.# format.'
        versions:
          type: array
          items:
            type: string
          description: A list of available versions for this policy definition.
      description: The policy definition properties.
    ErrorResponse:
      title: Error Response
      description: Common error response for all Azure Resource Manager APIs to return error details for failed operations. (This also follows the OData error response format.)
      type: object
      properties:
        code:
          readOnly: true
          type: string
          description: The error code.
        message:
          readOnly: true
          type: string
          description: The error message.
        target:
          readOnly: true
          type: string
          description: The error target.
        details:
          readOnly: true
          type: array
          items:
            $ref: '#/components/schemas/ErrorResponse'
          x-ms-identifiers:
          - message
          - target
          description: The error details.
        additionalInfo:
          readOnly: true
          type: array
          items:
            $ref: '#/components/schemas/ErrorAdditionalInfo'
          x-ms-identifiers: []
          description: The error additional info.
    PolicyDefinition_2:
      type: object
      properties:
        properties:
          $ref: '#/components/schemas/PolicyDefinitionProperties_2'
        id:
          readOnly: true
          type: string
          description: The ID of the policy definition.
        name:
          readOnly: true
          type: string
          description: The name of the policy definition.
        type:
          readOnly: true
          type: string
          description: The type of the resource (Microsoft.Authorization/policyDefinitions).
        systemData:
          $ref: '#/components/schemas/systemData'
      description: The policy definition.
      x-ms-azure-resource: true
    CloudError_2:
      type: object
      x-ms-external: true
      properties:
        error:
          $ref: '#/components/schemas/ErrorResponse'
      description: An error response from a policy operation.
    systemData:
      type: object
      description: Metadata pertaining to creation and last modification of the resource.
      properties:
        createdBy:
          type: string
          description: The identity that created the resource.
        createdByType:
          type: string
          description: The type of identity that created the resource.
          enum:
          - User
          - Application
          - ManagedIdentity
          - Key
          x-ms-enum:
            name: createdByType
            modelAsString: true
        createdAt:
          type: string
          format: date-time
          description: The timestamp of resource creation (UTC).
        lastModifiedBy:
          type: string
          description: The identity that last modified the resource.
        lastModifiedByType:
          type: string
          description: The type of identity that last modified the resource.
          enum:
          - User
          - Application
          - ManagedIdentity
          - Key
          x-ms-enum:
            name: createdByType
            modelAsString: true
        lastModifiedAt:
          type: string
          format: date-time
          description: The timestamp of resource last modification (UTC)
      readOnly: true
    PolicyDefinitionProperties_2:
      type: object
      properties:
        policyType:
          type: string
          description: The type of policy definition. Possible values are NotSpecified, BuiltIn, Custom, and Static.
          enum:
          - NotSpecified
          - BuiltIn
          - Custom
          - Static
          x-ms-enum:
            name: policyType
            modelAsString: true
        mode:
          type: string
          description: The policy definition mode. Some examples are All, Indexed, Microsoft.KeyVault.Data.
          default: Indexed
        displayName:
          type: string
          description: The display name of the policy definition.
        description:
          type: string
          description: The policy definition description.
        policyRule:
          type: object
          description: The policy rule.
        metadata:
          type: object
          description: The policy definition metadata.  Metadata is an open ended object and is typically a collection of key value pairs.
        parameters:
          $ref: '#/components/schemas/ParameterDefinitions'
        version:
          type: string
          description: 'The policy definition version in #.#.# format.'
        versions:
          type: array
          items:
            type: string
          description: A list of available versions for this policy definition.
      description: The policy definition properties.
    ErrorAdditionalInfo:
      type: object
      properties:
        type:
          readOnly: true
          type: string
          description: The additional info type.
        info:
          readOnly: true
          type: object
          description: The additional info.
      description: The resource management error additional info.
  parameters:
    TopParameter:
      name: $top
      in: query
      required: false
      description: Maximum number of records to return. When the $top filter is not provided, it will return 500 records.
      x-ms-parameter-location: method
      schema:
        type: integer
        format: int32
        maximum: 1000
        minimum: 1
    PolicyDefinitionsFilterParameter:
      name: $filter
      in: query
      required: false
      description: 'The filter to apply on the operation. Valid values for $filter are: ''atExactScope()'', ''policyType -eq {value}'' or ''category eq ''{value}''''. If $filter is not provided, no filtering is performed. If $filter=atExactScope() is provided, the returned list only includes all policy definitions that at the given scope. If $filter=''policyType -eq {value}'' is provided, the returned list only includes all policy definitions whose type match the {value}. Possible policyType values are NotSpecified, BuiltIn, Custom, and Static. If $filter=''category -eq {value}'' is provided, the returned list only includes all policy definitions whose category match the {value}.'
      x-ms-skip-url-encoding: true
      x-ms-parameter-location: method
      schema:
        type: string
    ManagementGroupIdParameter:
      name: managementGroupId
      in: path
      required: true
      description: The ID of the management group.
      x-ms-parameter-location: method
      schema:
        type: string
    SubscriptionIdParameter:
      name: subscriptionId
      in: path
      description: The ID of the target subscription. The value must be an UUID.
      required: true
      schema:
        type: string
        format: uuid
    PolicyDefinitionsFilterParameter_2:
      name: $filter
      in: query
      required: false
      description: 'The filter to apply on the operation. Valid values for $filter are: ''atExactScope()'', ''policyType -eq {value}'' or ''category eq ''{value}''''. If $filter is not provided, no filtering is performed. If $filter=atExactScope() is provided, the returned list only includes all policy definitions that at the given scope. If $filter=''policyType -eq {value}'' is provided, the returned list only includes all policy definitions whose type match the {value}. Possible policyType values are NotSpecified, BuiltIn, Custom, and Static. If $filter=''category -eq {value}'' is provided, the returned list only includes all policy definitions whose category match the {value}.'
      x-ms-parameter-location: method
      schema:
        type: string
      allowReserved: true
    ApiVersionParameter:
      name: api-version
      in: query
      description: The API version to use for this operation.
      required: true
      schema:
        type: string
        minLength: 1
  requestBodies:
    PolicyDefinition:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PolicyDefinition_2'
      description: The policy definition properties.
      required: true
  securitySchemes:
    azure_auth:
      type: oauth2
      flows:
        implicit:
          scopes:
            user_impersonation: impersonate your user account
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize
      description: Azure Active Directory OAuth2 Flow.
x-refined-from:
- policyDefinitions.json
- microsoft-azure-policy-openapi.yml