How to use Azure API Management with virtual networks

Azure Virtual Networks (VNETs) allow you to place any of your Azure resources in a non-internet routable network that you control access to. These networks can then be connected to your on-premises networks using various VPN technologies. To learn more about Azure Virtual Networks start with the information here: Azure Virtual Network Overview.

Azure API Management can be deployed inside the virtual network (VNET), so it can access backend services within the network. The developer portal and API gateway, can be configured to be accessible either from the Internet or only within the virtual network.


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


This article has been updated to use the new Azure PowerShell Az module. You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. For Az module installation instructions, see Install Azure PowerShell.



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


To perform the steps described in this article, you must have:

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 Virtual network.

    Virtual network menu of API Management

  5. Select the desired access type:

    • Off: This is the default. API Management is not deployed into a virtual network.

    • 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 virtual network.

      Public peering

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

      Private peering

  6. If you selected External or Internal, you will see a list of all regions where your API Management service is provisioned. Choose a Location, and then pick its Virtual network and Subnet. The virtual network list is populated with both classic and Resource Manager virtual networks available in your Azure subscriptions that are set up in the region you are configuring.


    When deploying an Azure API Management instance to a Resource Manager VNET, the service must be in a dedicated subnet that contains no other resources except for Azure API Management instances. If an attempt is made to deploy an Azure API Management instance to a Resource Manager VNET subnet that contains other resources, the deployment will fail.

    Then select Apply. The Virtual network page of your API Management instance is updated with your new virtual network and subnet choices.

    Select VPN

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


The VIP address of the API Management instance will change each time VNET is enabled or disabled. The VIP address will also change when API Management is moved from External to Internal, or vice-versa.


If you remove API Management from a VNET or change the one it is deployed in, the previously used VNET can remain locked for up to six hours. During this period it will not be possible to delete the VNET or deploy a new resource to it. This behavior is true for clients using api-version 2018-01-01 and earlier. Clients using api-version 2019-01-01 and later, the VNET is freed up as soon as the associated API Management service is deleted.

Enable VNET connection using PowerShell cmdlets

You can also enable VNET connectivity using the PowerShell cmdlets.

  • Create an API Management service inside a VNET: Use the cmdlet New-AzApiManagement to create an Azure API Management service inside a VNET.

  • Deploy an existing API Management service inside a VNET: Use the cmdlet Update-AzApiManagementRegion to move an existing Azure API Management service inside a Virtual Network.

Connect to a web service hosted within a virtual Network

After your API Management service is connected to the VNET, accessing backend services within it is no different than accessing public services. Just type in 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 when creating a new API or editing an existing one.

Add API from VPN

Common Network Configuration Issues

Following is a list of common misconfiguration issues that can occur while deploying API Management service into a Virtual Network.

  • 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. Please follow this guidance on custom DNS setup. See the ports table below and other network requirements for reference.


If you plan to use a Custom DNS Server(s) for the VNET, you should set it up before deploying an API Management service into it. Otherwise you 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: Inbound and Outbound traffic into the Subnet in which API Management is deployed can be controlled using Network Security Group. If any of these ports are unavailable, API Management may not operate properly and may become inaccessible. Having one or more of these ports blocked is 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 (*) Virtual Network 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 (where applicable) External & Internal
* / 1433 Outbound TCP VIRTUAL_NETWORK / SQL Access to Azure SQL endpoints 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


The Ports for which the Purpose is bold 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 contain 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. As shown in the table, these URLs are represented under the AzureMonitor service tag for use with Network Security Groups.

    Azure Environment Endpoints
    Azure Public
    • be deprecated)
    • be deprecated)
    • be deprecated)
    • be deprecated)
    • be deprecated)
    • be deprecated)
    Azure Government
    • be deprecated)
    • be deprecated)
    • be deprecated)
    Azure China 21Vianet
    • be deprecated)
    • be deprecated)
    • be deprecated)


    The change of clusters above with dns zone to is mostly a DNS Change. IP Address of cluster will not change.

  • 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.

  • 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: To enable the flow of diagnostic logs from Azure portal when using the API Management extension from inside a Virtual Network, outbound access to on port 443 is required. This helps in troubleshooting issues you might face when using extension.

  • Azure Load Balancer: Allowing Inbound request from Service Tag AZURE_LOAD_BALANCER is not a requirement for the Developer SKU, since we only deploy one unit of Compute behind it. But Inbound from becomes critical when scaling to higher SKU like Premium, as failure of Health Probe from Load Balancer, fails a deployment.

  • Application Insights: If Azure Application Insights monitoring is enabled on API Management, then we need to allow outbound connectivity to the Telemetry endpoint from the Virtual Network.

  • Force Tunneling Traffic to On-premises Firewall Using Express Route or Network Virtual Appliance: A common customer configuration is to define their own default route ( which forces all traffic from the API Management delegated subnet to flow through an on-premises firewall or to a Network virtual appliance. This traffic flow invariably breaks connectivity with Azure API Management because the outbound traffic is either blocked on-premises, or NAT'd to an unrecognizable set of addresses that no longer work with various Azure endpoints. The solution requires you to do a couple of things:

    • Enable service endpoints on the subnet in which the API Management service is deployed. Service Endpoints need to be enabled for Azure Sql, Azure Storage, Azure EventHub and Azure ServiceBus. Enabling endpoints directly from API Management delegated subnet to these services allows them to use the Microsoft Azure backbone network providing optimal routing for service traffic. If you use Service Endpoints with a forced tunneled Api Management, the above Azure services traffic isn't forced tunneled. The other API Management service dependency traffic is forced tunneled and can't be lost or the API Management service would not function properly.

    • All the control plane traffic from Internet to the management endpoint of your API Management service are 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, we need to add the following user-defined routes (UDRs) to steer traffic back to Azure by setting the destination of these host routes to "Internet". The set of Inbound IPs for control Plane traffic is documented Control Plane IP Addresses

    • For other API Management service dependencies which are force tunneled, there should be a way to resolve the hostname and reach out to the endpoint. These include

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


  • Initial Setup: When the initial deployment of API Management service into a subnet does not succeed, it is advised to first deploy a virtual machine into the same subnet. Next remote desktop into the virtual machine and validate that there is connectivity to one of each resource below in your Azure subscription

    • Azure Storage blob
    • Azure SQL Database
    • Azure Storage Table


    After you have validated the connectivity, make sure to remove all the resources deployed in the subnet, before deploying API Management into the subnet.

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

  • Resource Navigation Links: When deploying into Resource Manager style vnet subnet, 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 move an API Management service to a different subnet or delete it, we will remove that resource navigation link.

Subnet Size Requirement

Azure reserves some IP addresses within each subnet, and these addresses can't be used. The first and last IP addresses of the subnets are reserved for protocol conformance, along with three more addresses 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 additional IP address for the external load balancer. When deploying into Internal virtual network, it requires an additional 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 that gives three usable IP addresses.

Each additional 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.
  • An IP address from a subnet IP range (DIP) will be used to access resources within the vnet and a public IP address (VIP) will be used to access resources outside the vnet.
  • Load balanced public IP address can be found on the Overview/Essentials blade in the Azure portal.


  • A subnet containing API Management instances cannot 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 virtual network mode, users are responsible for managing the load balancing across multiple regions, as they own the routing.
  • Connectivity from a resource in a globally peered VNET in another region to API Management service in Internal mode will not work due to platform limitation. 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 address marked with Global must be whitelisted 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 West Central US
Azure Public Korea Central
Azure Public UK West
Azure Public Japan West
Azure Public North Central US
Azure Public UK South
Azure Public West India
Azure Public East US
Azure Public West Europe
Azure Public Japan East
Azure Public France Central
Azure Public Canada East
Azure Public UAE North
Azure Public Brazil South
Azure Public Southeast Asia
Azure Public South Africa North
Azure Public Canada Central
Azure Public Korea South
Azure Public Central India
Azure Public West US
Azure Public Australia Southeast
Azure Public Australia Central
Azure Public South India
Azure Public Central US
Azure Public Australia East
Azure Public West US 2
Azure Public East US 2 EUAP
Azure Public Central US EUAP
Azure Public South Central US
Azure Public East US 2
Azure Public North Europe
Azure Public East Asia
Azure Public France South
Azure Public Switzerland West
Azure Public Australia Central 2
Azure Public UAE Central
Azure Public Switzerland North
Azure Public South Africa West
Azure Public Germany West Central
Azure Public Germany North
Azure Public Norway East
Azure Public Norway West
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