Connect to a virtual network using Azure API Management

With Azure Virtual Networks (VNETs), you can place any of your Azure resources in a non-internet-routable network to which you control access. You can then connect VNETs to your on-premises networks using various VPN technologies. To learn more about Azure VNETs, start with the information in the Azure Virtual Network Overview.

Azure API Management can be deployed inside the VNET to access backend services within the network. You can configure the developer portal and API gateway to be accessible either from the internet or only within the VNET.

This article explains VNET connectivity options, settings, limitations, and troubleshooting steps for your API Management instance. For configurations specific to the internal mode, where the developer portal and API gateway are accessible only within the VNET, see Connect to an internal virtual network using Azure API Management.


The API import document URL must be hosted on a publicly accessible internet address.


This article has been updated to use the Azure Az PowerShell module. The Az PowerShell module is the recommended PowerShell module for interacting with Azure. To get started with the Az PowerShell module, see Install Azure PowerShell. To learn how to migrate to the Az PowerShell module, see Migrate Azure PowerShell from AzureRM to Az.



This feature is available in the Premium and Developer tiers of API Management.


  • A Standard SKU public IPv4 address, if your client uses API version 2021-01-01-preview or later. The public IP address resource is required when setting up the virtual network for either external or internal access. With an internal virtual network, the public IP address is used only for management operations. Learn more about IP addresses of API Management.

    • The IP address must be in the same region and subscription as the API Management instance and the virtual network.

    • The value of the IP address is assigned as the virtual public IPv4 address of the API Management instance in that region.

    • When changing from an external to internal virtual network (or vice versa), changing subnets in the network, or updating availability zones for the API Management instance, you must configure a different public IP address.


    Currently, the Azure portal uses API version 2021-01-01 preview when creating or updating an API Management instance. You can specify this API version using an Azure Resource Manager template or the API Management REST API. The Azure CLI and Azure PowerShell currently support API version 2020-12-01.

Enable VNET connection

Enable VNET connectivity using the Azure portal

  1. Go to the Azure portal to find your API management instance. Search for and select API Management services.

  2. Choose your API Management instance.

  3. Select Virtual network.

  4. Configure the API Management instance to be deployed inside a VNET.

    Select VNET in Azure portal.

  5. Select the desired access type:

    • Off: Default type. API Management is not deployed into a VNET.

    • External: The API Management gateway and developer portal are accessible from the public internet via an external load balancer. The gateway can access resources within the VNET.

      Public peering

    • Internal: The API Management gateway and developer portal are accessible only from within the VNET via an internal load balancer. The gateway can access resources within the VNET.

      Private peering

  6. If you selected External or Internal, you will see a list of all locations (regions) where your API Management service is provisioned.

  7. Choose a Location.

  8. Pick Virtual network, Subnet, and IP address.

    • The VNET list is populated with Resource Manager VNETs available in your Azure subscriptions, set up in the region you are configuring.

      VNET settings in the portal.


      • If using API version 2020-12-01 or earlier to deploy an Azure API Management instance in a Resource Manager VNET: The service must be in a dedicated subnet that contains only Azure API Management instances. Attempting to deploy an Azure API Management instance to a Resource Manager VNET subnet that contains other resources will cause the deployment to fail.

      • If using API version 2021-01-01-preview or later to deploy an Azure API Management instance in a VNET: Only a Resource Manager VNET is supported, but the subnet used may contain other resources. You don't have to use a subnet dedicated to API Management instances.

  9. Select Apply. The Virtual network page of your API Management instance is updated with your new VNET and subnet choices.

  10. Continue configuring VNET settings for the remaining locations of your API Management instance.

  11. In the top navigation bar, select Save, then select Apply network configuration.

    It can take 15 to 45 minutes to update the API Management instance.


With clients using API version 2020-12-01 and earlier, the VIP address of the API Management instance will change when:

  • The VNET is enabled or disabled.
  • API Management is moved from External to Internal virtual network, or vice versa.


  • If you are using API version 2018-01-01 and earlier:
    The VNET will lock for up to six hours if you remove API Management from a VNET or change the VNET. During these six hours, you can't delete the VNET or deploy a new resource to it.

  • If you are using API version 2019-01-01 and later:
    The VNET is available as soon as the associated API Management service is deleted.

Deploy API Management into External VNET

You can also enable VNET connectivity by using the following methods.

API version 2021-01-01-preview

API version 2020-12-01

  • Azure Resource Manager template

    Deploy to Azure

  • Azure PowerShell cmdlets - Create or update an API Management instance in a VNET

Connect to a web service hosted within a virtual network

Once you've connected your API Management service to the VNET, you'll be able to access backend services within it just as you do public services. When creating or editing an API, type the local IP address or the host name (if a DNS server is configured for the VNET) of your web service into the Web service URL field.

Add API from VPN

Common Network Configuration Issues

Common misconfiguration issues that can occur while deploying API Management service into a VNET include:

  • Custom DNS server setup:
    The API Management service depends on several Azure services. When API Management is hosted in a VNET with a custom DNS server, it needs to resolve the hostnames of those Azure services.


    If you plan to use a Custom DNS server(s) for the VNET, set it up before deploying an API Management service into it. Otherwise, you'll need to update the API Management service each time you change the DNS Server(s) by running the Apply Network Configuration Operation.

  • Ports required for API Management:
    You can control inbound and outbound traffic into the subnet in which API Management is deployed by using [network security groups][network security groups]. If any of the following ports are unavailable, API Management may not operate properly and may become inaccessible. Blocked ports are another common misconfiguration issue when using API Management with a VNET.

When an API Management service instance is hosted in a VNET, the ports in the following table are used.

Source / Destination Port(s) Direction Transport protocol Service Tags
Source / Destination
Purpose (*) VNET type
* / [80], 443 Inbound TCP INTERNET / VIRTUAL_NETWORK Client communication to API Management External
* / 3443 Inbound TCP ApiManagement / VIRTUAL_NETWORK Management endpoint for Azure portal and PowerShell External & Internal
* / 443 Outbound TCP VIRTUAL_NETWORK / Storage Dependency on Azure Storage External & Internal
* / 443 Outbound TCP VIRTUAL_NETWORK / AzureActiveDirectory Azure Active Directory and Azure KeyVault dependency External & Internal
* / 1433 Outbound TCP VIRTUAL_NETWORK / SQL Access to Azure SQL endpoints External & Internal
* / 443 Outbound TCP VIRTUAL_NETWORK / AzureKeyVault Access to Azure KeyVault External & Internal
* / 5671, 5672, 443 Outbound TCP VIRTUAL_NETWORK / EventHub Dependency for Log to Event Hub policy and monitoring agent External & Internal
* / 445 Outbound TCP VIRTUAL_NETWORK / Storage Dependency on Azure File Share for GIT External & Internal
* / 443, 12000 Outbound TCP VIRTUAL_NETWORK / AzureCloud Health and Monitoring Extension External & Internal
* / 1886, 443 Outbound TCP VIRTUAL_NETWORK / AzureMonitor Publish Diagnostics Logs and Metrics, Resource Health, and Application Insights External & Internal
* / 25, 587, 25028 Outbound TCP VIRTUAL_NETWORK / INTERNET Connect to SMTP Relay for sending e-mails External & Internal
* / 6381 - 6383 Inbound & Outbound TCP VIRTUAL_NETWORK / VIRTUAL_NETWORK Access Redis Service for Cache policies between machines External & Internal
* / 4290 Inbound & Outbound UDP VIRTUAL_NETWORK / VIRTUAL_NETWORK Sync Counters for Rate Limit policies between machines External & Internal
* / * Inbound TCP AZURE_LOAD_BALANCER / VIRTUAL_NETWORK Azure Infrastructure Load Balancer External & Internal


Bold items in the Purpose column are required for API Management service to be deployed successfully. Blocking the other ports, however, will cause degradation in the ability to use and monitor the running service and provide the committed SLA.

  • TLS functionality:
    To enable TLS/SSL certificate chain building and validation, the API Management service needs outbound network connectivity to,, and This dependency is not required if any certificate you upload to API Management contains the full chain to the CA root.

  • DNS Access:
    Outbound access on port 53 is required for communication with DNS servers. If a custom DNS server exists on the other end of a VPN gateway, the DNS server must be reachable from the subnet hosting API Management.

  • Metrics and Health Monitoring:
    Outbound network connectivity to Azure Monitoring endpoints, which resolve under the following domains, are represented under the AzureMonitor service tag for use with Network Security Groups.

    Azure Environment Endpoints
    Azure Public
    Azure Government
    Azure China 21Vianet
  • Regional Service Tags: NSG rules allowing outbound connectivity to Storage, SQL, and Event Hubs service tags may use the regional versions of those tags corresponding to the region containing the API Management instance (for example, Storage.WestUS for an API Management instance in the West US region). In multi-region deployments, the NSG in each region should allow traffic to the service tags for that region and the primary region.


    Enable publishing the developer portal for an API Management instance in a VNET by allowing outbound connectivity to blob storage in the West US region. For example, use the Storage.WestUS service tag in an NSG rule. Currently, connectivity to blob storage in the West US region is required to publish the developer portal for any API Management instance.

  • SMTP Relay:
    Outbound network connectivity for the SMTP Relay, which resolves under the host,,, and

  • Developer portal CAPTCHA:
    Outbound network connectivity for the developer portal's CAPTCHA, which resolves under the hosts and

  • Azure portal Diagnostics:
    When using the API Management extension from inside a VNET, outbound access to on port 443 is required to enable the flow of diagnostic logs from Azure portal. This access helps in troubleshooting issues you might face when using extension.

  • Azure Load Balancer:
    You're not required to allow inbound request from service tag AZURE_LOAD_BALANCER for the Developer SKU, since only one compute unit is deployed behind it. But inbound from becomes critical when scaling to a higher SKU, like Premium, as failure of health probe from load balancer then fails a deployment.

  • Application Insights:
    If you've enabled Azure Application Insights monitoring on API Management, allow outbound connectivity to the Telemetry endpoint from the VNET.

  • Force Tunneling Traffic to On-premises Firewall Using Express Route or Network Virtual Appliance:
    Commonly, you configure and define your own default route (, forcing all traffic from the API Management-delegated subnet to flow through an on-premises firewall or to a network virtual appliance. This traffic flow breaks connectivity with Azure API Management, since outbound traffic is either blocked on-premises, or NAT'd to an unrecognizable set of addresses no longer working with various Azure endpoints. You can solve this issue via a couple of methods:

    • Enable service endpoints on the subnet in which the API Management service is deployed for:

      • Azure Sql
      • Azure Storage
      • Azure EventHub, and
      • Azure KeyVault.

      By enabling endpoints directly from API Management-delegated subnet to these services, you can use the Microsoft Azure backbone network, providing optimal routing for service traffic. If you use service endpoints with a force tunneled API Management, the above Azure services traffic isn't force tunneled. The other API Management service dependency traffic is force tunneled and can't be lost. If lost, the API Management service would not function properly.

    • All the control plane traffic from the internet to the management endpoint of your API Management service is routed through a specific set of inbound IPs, hosted by API Management. When the traffic is force tunneled, the responses will not symmetrically map back to these inbound source IPs. To overcome the limitation, set the destination of the following user-defined routes (UDRs) to the "Internet", to steer traffic back to Azure. Find the set of inbound IPs for control plane traffic documented in Control Plane IP Addresses.

    • For other force tunneled API Management service dependencies, resolve the hostname and reach out to the endpoint. These include:

      • Metrics and Health Monitoring
      • Azure portal Diagnostics
      • SMTP Relay
      • Developer portal CAPTCHA


  • Unsuccessful initial deployment of API Management service into a subnet:

    • Deploy a virtual machine into the same subnet.
    • Remote desktop into the virtual machine and validate connectivity to one of each of the following resources in your Azure subscription:
      • Azure Storage blob
      • Azure SQL Database
      • Azure Storage Table


    After validating the connectivity, remove all the resources in the subnet before deploying API Management into the subnet.

  • Verify network connectivity status:

    • After deploying API Management into the subnet, use the portal to check the connectivity of your instance to dependencies, such as Azure Storage.
    • In the portal, in the left-hand menu, under Deployment and infrastructure, select Network connectivity status.

    Verify network connectivity status in the portal

    Filter Description
    Required Select to review the required Azure services connectivity for API Management. Failure indicates that the instance is unable to perform core operations to manage APIs
    Optional Select to review the optional services connectivity. Failure indicates only that the specific functionality will not work (for example, SMTP). Failure may lead to degradation in using and monitoring the API Management instance and providing the committed SLA.

    To address connectivity issues, review Common network configuration issues and fix required network settings.

  • Incremental Updates:
    When making changes to your network, refer to NetworkStatus API to verify that the API Management service has not lost access to critical resources. The connectivity status should be updated every 15 minutes.

  • Resource Navigation Links:
    When deploying into a Resource Manager VNET subnet with API version 2020-12-01 and earlier, API Management reserves the subnet by creating a resource navigation link. If the subnet already contains a resource from a different provider, deployment will fail. Similarly, when you delete an API Management service, or move it to a different subnet, the resource navigation link will be removed.

Subnet Size Requirement

Azure reserves some IP addresses within each subnet, which can't be used. The first and last IP addresses of the subnets are reserved for protocol conformance. Three more addresses are used for Azure services. For more information, see Are there any restrictions on using IP addresses within these subnets?.

In addition to the IP addresses used by the Azure VNET infrastructure, each API Management instance in the subnet uses:

  • Two IP addresses per unit of Premium SKU, or
  • One IP address for the Developer SKU.

Each instance reserves an extra IP address for the external load balancer. When deploying into internal VNET, the instance requires an extra IP address for the internal load balancer.

Given the calculation above, the minimum size of the subnet in which API Management can be deployed is /29, which gives three usable IP addresses. Each extra scale unit of API Management requires two more IP addresses.


  • A load balanced public IP address (VIP) will be reserved to provide access to all service endpoints and resources outside the VNET.
    • Load balanced public IP addresses can be found on the Overview/Essentials blade in the Azure portal.
  • An IP address from a subnet IP range (DIP) will be used to access resources within the VNET.


  • For API version 2020-12-01 and earlier, a subnet containing API Management instances can't contain any other Azure resource types.
  • The subnet and the API Management service must be in the same subscription.
  • A subnet containing API Management instances cannot be moved across subscriptions.
  • For multi-region API Management deployments configured in internal VNET mode, users own the routing and are responsible for managing the load balancing across multiple regions.
  • Due to platform limitations, connectivity between a resource in a globally peered VNET in another region and an API Management service in internal mode will not work. For more information, see Resources in one virtual network cannot communicate with Azure internal load balancer in peered virtual network.

Control Plane IP Addresses

The IP Addresses are divided by Azure Environment. When allowing inbound requests, IP addresses marked with Global must be permitted, along with the Region-specific IP address.

Azure Environment Region IP address
Azure Public South Central US (Global)
Azure Public North Central US (Global)
Azure Public Australia Central
Azure Public Australia Central 2
Azure Public Australia East
Azure Public Australia Southeast
Azure Public Brazil South
Azure Public Brazil Southeast
Azure Public Canada Central
Azure Public Canada East
Azure Public Central India
Azure Public Central US
Azure Public Central US EUAP
Azure Public East Asia
Azure Public East US
Azure Public East US 2
Azure Public East US 2 EUAP
Azure Public France Central
Azure Public France South
Azure Public Germany North
Azure Public Germany West Central
Azure Public Japan East
Azure Public Japan West
Azure Public Jio India Central
Azure Public Jio India West
Azure Public Korea Central
Azure Public Korea South
Azure Public North Central US
Azure Public North Europe
Azure Public Norway East
Azure Public Norway West
Azure Public South Africa North
Azure Public South Africa West
Azure Public South Central US
Azure Public South India
Azure Public Southeast Asia
Azure Public Switzerland North
Azure Public Switzerland West
Azure Public UAE Central
Azure Public UAE North
Azure Public UK South
Azure Public UK West
Azure Public West Central US
Azure Public West Europe
Azure Public West India
Azure Public West US
Azure Public West US 2
Azure Public West US 3
Azure China 21Vianet China North (Global)
Azure China 21Vianet China East (Global)
Azure China 21Vianet China North
Azure China 21Vianet China East
Azure China 21Vianet China North 2
Azure China 21Vianet China East 2
Azure Government USGov Virginia (Global)
Azure Government USGov Texas (Global)
Azure Government USGov Virginia
Azure Government USGov Iowa
Azure Government USGov Arizona
Azure Government USGov Texas
Azure Government USDoD Central
Azure Government USDoD East