Microsoft Defender Private Links API

openapi: 3.2.0
info:
  title: Microsoft Defender for Cloud REST API (Microsoft.Security)…
  version: stable-composite
  description: Composite of the latest stable Microsoft.Security resource-manager swagger files published by Microsoft in Azure/azure-rest-api-specs. Each path keeps its own api-version via x-source.
  x-source-repo: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/security/resource-manager/Microsoft.Security/Security
servers:
- url: https://management.azure.com
security:
- azure_auth:
  - user_impersonation
tags:
- name: PrivateLinks
paths:
  /subscriptions/{subscriptionId}/providers/Microsoft.Security/privateLinks:
    get:
      operationId: PrivateLinks_ListBySubscription
      tags:
      - PrivateLinks
      description: Lists all the private links in the specified subscription. private links enable secure, private connectivity to Microsoft Defender for Cloud services without exposing traffic to the public internet. Use the 'nextLink' property in the response to get the next page of private links for the specified subscription.
      parameters:
      - $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      - $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter
      responses:
        '200':
          description: Azure operation completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateLinksList'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/definitions/ErrorResponse
      x-ms-examples:
        List private links by subscription:
          $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/security/resource-manager/Microsoft.Security/Security/stable/2026-01-01/examples/PrivateLinks/PrivateLinks_ListBySubscription.json
      x-ms-pageable:
        nextLinkName: nextLink
      x-source: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/security/resource-manager/Microsoft.Security/Security/stable/2026-01-01/privateLinks.json
      summary: Private links list by subscription
      x-summary-source: derived
  /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Security/privateLinks:
    get:
      operationId: PrivateLinks_List
      tags:
      - PrivateLinks
      description: Lists all the private links in the specified resource group. private links enable secure, private connectivity to Microsoft Defender for Cloud services without exposing traffic to the public internet. Use the 'nextLink' property in the response to get the next page of private links for the specified resource group.
      parameters:
      - $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      - $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter
      - $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/parameters/ResourceGroupNameParameter
      responses:
        '200':
          description: Azure operation completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateLinksList'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/definitions/ErrorResponse
      x-ms-examples:
        List private links:
          $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/security/resource-manager/Microsoft.Security/Security/stable/2026-01-01/examples/PrivateLinks/PrivateLinks_List.json
      x-ms-pageable:
        nextLinkName: nextLink
      x-source: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/security/resource-manager/Microsoft.Security/Security/stable/2026-01-01/privateLinks.json
      summary: Private links list
      x-summary-source: derived
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Security/privateLinks/{privateLinkName}
  : get:
      operationId: PrivateLinks_Get
      tags:
      - PrivateLinks
      description: Get a private link resource. Returns the configuration and status of private endpoint connectivity for Microsoft Defender for Cloud services in the specified region.
      parameters:
      - $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      - $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter
      - $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/parameters/ResourceGroupNameParameter
      - name: privateLinkName
        in: path
        description: The name of the private link resource. Must be unique within the resource group and follow Azure naming conventions.
        required: true
        schema:
          type: string
          maxLength: 63
          minLength: 3
          pattern: ^[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*$
      responses:
        '200':
          description: Azure operation completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateLinkResource'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/definitions/ErrorResponse
      x-ms-examples:
        Get private link:
          $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/security/resource-manager/Microsoft.Security/Security/stable/2026-01-01/examples/PrivateLinks/PrivateLinks_Get.json
      x-source: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/security/resource-manager/Microsoft.Security/Security/stable/2026-01-01/privateLinks.json
      summary: Private links get
      x-summary-source: derived
    put:
      operationId: PrivateLinks_Create
      tags:
      - PrivateLinks
      description: Create a private link resource. This operation creates the necessary infrastructure to enable private endpoint connections to Microsoft Defender for Cloud services. For updates to existing resources, use the PATCH operation. The operation is asynchronous and may take several minutes to complete.
      parameters:
      - $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      - $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter
      - $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/parameters/ResourceGroupNameParameter
      - name: privateLinkName
        in: path
        description: The name of the private link resource. Must be unique within the resource group and follow Azure naming conventions.
        required: true
        schema:
          type: string
          maxLength: 63
          minLength: 3
          pattern: ^[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*$
      responses:
        '200':
          description: Resource 'PrivateLinkResource' update operation succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateLinkResource'
        '201':
          description: Resource 'PrivateLinkResource' create operation succeeded
          headers:
            Azure-AsyncOperation:
              description: A link to the status monitor
              schema:
                type: string
            Retry-After:
              description: The Retry-After header can indicate how long the client should wait before polling the operation status.
              schema:
                type: integer
                format: int32
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateLinkResource'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/definitions/ErrorResponse
      x-ms-examples:
        Create private link:
          $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/security/resource-manager/Microsoft.Security/Security/stable/2026-01-01/examples/PrivateLinks/PrivateLinks_Create.json
      x-ms-long-running-operation-options:
        final-state-via: azure-async-operation
        final-state-schema: '#/definitions/PrivateLinkResource'
      x-ms-long-running-operation: true
      x-source: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/security/resource-manager/Microsoft.Security/Security/stable/2026-01-01/privateLinks.json
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrivateLinkResource'
        description: Private link request payload containing the resource information for create operations.
        required: true
      summary: Private links create
      x-summary-source: derived
    patch:
      operationId: PrivateLinks_Update
      tags:
      - PrivateLinks
      description: Update specific properties of a private link resource. Use this operation to update mutable properties like tags without affecting the entire resource configuration.
      parameters:
      - $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      - $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter
      - $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/parameters/ResourceGroupNameParameter
      - name: privateLinkName
        in: path
        description: The name of the private link resource. Must be unique within the resource group and follow Azure naming conventions.
        required: true
        schema:
          type: string
          maxLength: 63
          minLength: 3
          pattern: ^[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*$
      responses:
        '200':
          description: Azure operation completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateLinkResource'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/definitions/ErrorResponse
      x-ms-examples:
        Update private link:
          $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/security/resource-manager/Microsoft.Security/Security/stable/2026-01-01/examples/PrivateLinks/PrivateLinks_Update.json
      x-source: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/security/resource-manager/Microsoft.Security/Security/stable/2026-01-01/privateLinks.json
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrivateLinkUpdate'
        description: private link update payload containing only the properties to be updated.
        required: true
      summary: Private links update
      x-summary-source: derived
    delete:
      operationId: PrivateLinks_Delete
      tags:
      - PrivateLinks
      description: Delete a private link resource. This operation will remove the private link infrastructure and disconnect all associated private endpoints. This operation is asynchronous and may take several minutes to complete.
      parameters:
      - $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      - $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter
      - $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/parameters/ResourceGroupNameParameter
      - name: privateLinkName
        in: path
        description: The name of the private link resource. Must be unique within the resource group and follow Azure naming conventions.
        required: true
        schema:
          type: string
          maxLength: 63
          minLength: 3
          pattern: ^[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*$
      responses:
        '202':
          description: Resource deletion accepted.
          headers:
            Azure-AsyncOperation:
              description: A link to the status monitor
              schema:
                type: string
                format: uri
            Location:
              description: The Location header contains the URL where the status of the long running operation can be checked.
              schema:
                type: string
            Retry-After:
              description: The Retry-After header can indicate how long the client should wait before polling the operation status.
              schema:
                type: integer
                format: int32
        '204':
          description: Resource does not exist.
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/definitions/ErrorResponse
      x-ms-examples:
        Delete private link:
          $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/security/resource-manager/Microsoft.Security/Security/stable/2026-01-01/examples/PrivateLinks/PrivateLinks_Delete.json
      x-ms-long-running-operation-options:
        final-state-via: azure-async-operation
      x-ms-long-running-operation: true
      x-source: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/security/resource-manager/Microsoft.Security/Security/stable/2026-01-01/privateLinks.json
      summary: Private links delete
      x-summary-source: derived
components:
  schemas:
    PrivateLinkGroupResource:
      type: object
      description: A private link group resource that describes a grouping for the private link.
      properties:
        properties:
          $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/privatelinks.json#/definitions/PrivateLinkResourceProperties
          description: Resource properties.
          x-ms-client-flatten: true
      allOf:
      - $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/definitions/ProxyResource
    PrivateLinkUpdate:
      type: object
      description: Request payload for updating a private link resource. Used in PATCH operations to update specific mutable properties without affecting the entire resource configuration.
      properties:
        tags:
          type: object
          description: Resource tags
          additionalProperties:
            type: string
    PrivateLinksList:
      type: object
      description: Paginated list of private link resources. Contains an array of private links and optional pagination information.
      properties:
        value:
          type: array
          description: The PrivateLinkResource items on this page
          items:
            $ref: '#/components/schemas/PrivateLinkResource'
          readOnly: true
        nextLink:
          type: string
          description: The link to the next page of items
      required:
      - value
    PrivateLinkProperties:
      type: object
      description: Properties of a private link resource. These properties control the behavior and configuration of private endpoint connectivity to Defender services.
      properties:
        provisioningState:
          $ref: '#/components/schemas/Common.ProvisioningState'
          description: The current provisioning state of the private link resource. Indicates whether the resource is being created, updated, deleted, or has completed successfully.
          readOnly: true
        privateEndpointConnections:
          type: array
          description: List of private endpoint connections associated with this private link. Each connection represents a private endpoint from a customer's virtual network.
          items:
            $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/privatelinks.json#/definitions/PrivateEndpointConnection
          readOnly: true
        privateLinkResources:
          type: array
          description: List of private link resources available for connection. For Defender services, this typically includes the 'containers' group with 'api' and regional data endpoints.
          items:
            $ref: '#/components/schemas/PrivateLinkGroupResource'
          readOnly: true
        publicNetworkAccess:
          type: string
          description: This determines if traffic is allowed over public network. By default it is disabled.
          default: Disabled
          enum:
          - Enabled
          - Disabled
          x-ms-enum:
            name: PublicNetworkAccess
            modelAsString: true
            values:
            - name: Enabled
              value: Enabled
              description: Enabled
            - name: Disabled
              value: Disabled
              description: Disabled
    Common.ProvisioningState:
      type: string
      description: The current provisioning state of the resource. Indicates the status of the last operation performed on the resource.
      enum:
      - Succeeded
      - Creating
      - Updating
      - Deleting
      - Failed
      - Canceled
      - InProgress
      x-ms-enum:
        name: ProvisioningState
        modelAsString: true
        values:
        - name: Succeeded
          value: Succeeded
          description: The resource has been successfully provisioned and is ready for use.
        - name: Creating
          value: Creating
          description: The resource is being created. This is a transitional state.
        - name: Updating
          value: Updating
          description: The resource is being updated. This is a transitional state.
        - name: Deleting
          value: Deleting
          description: The resource is being deleted. This is a transitional state.
        - name: Failed
          value: Failed
          description: The last operation on the resource failed. Check the error details for more information.
        - name: Canceled
          value: Canceled
          description: The operation was canceled before completion.
        - name: InProgress
          value: InProgress
          description: InProgress
    PrivateLinkResource:
      type: object
      description: A private link resource that enables secure, private connectivity to Microsoft Defender for Cloud services. This resource manages the lifecycle of private endpoint connections and provides the necessary infrastructure for private connectivity.
      properties:
        properties:
          $ref: '#/components/schemas/PrivateLinkProperties'
          description: Properties specific to the private link resource
          x-ms-client-flatten: true
      required:
      - properties
      allOf:
      - $ref: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/common-types/resource-management/v5/types.json#/definitions/TrackedResource
  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.