Connect to a virtual network in internal mode using Azure API Management

With Azure virtual networks (VNETs), Azure API Management can manage internet-inaccessible APIs using several VPN technologies to make the connection. You can deploy API Management either via external or internal modes. For VNET connectivity options, requirements, and considerations, see Using a virtual network with Azure API Management.

In this article, you'll learn how to deploy API Management in internal VNET mode. In this mode, you can only view the following service endpoints within a VNET whose access you control.

  • The API gateway
  • The developer portal
  • Direct management
  • Git


None of the service endpoints are registered on the public DNS. The service endpoints remain inaccessible until you configure DNS for the VNET.

Use API Management in internal mode to:

  • Make APIs hosted in your private datacenter securely accessible by third parties outside of it by using Azure VPN connections or Azure ExpressRoute.
  • Enable hybrid cloud scenarios by exposing your cloud-based APIs and on-premises APIs through a common gateway.
  • Manage your APIs hosted in multiple geographic locations, using a single gateway endpoint.

Connect to internal VNET


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.


Some prerequisites differ depending on the version (stv2 or stv1) of the compute platform for your API Management instance.


When you use the portal to create or update the network configuration of your API Management instance, the instance is hosted on then stv2 compute platform.

  • A virtual network and subnet in the same region and subscription as your API Management instance. The subnet may contain other Azure resources.
  • A Standard SKU public IPv4 address. 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.


When you deploy an API Management service in an internal virtual network on the stv2 platform, it's hosted behind an internal load balancer in the Standard SKU, using the public IP address resource.

Enable VNET connection

Enable VNET connectivity using the Azure portal (stv2 platform)

  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. Select the Internal access type.

  5. In the list of locations (regions) where your API Management service is provisioned:

    1. Choose a Location.
    2. Select 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.
  6. Select Apply. The Virtual network page of your API Management instance is updated with your new VNET and subnet choices. Set up internal VNET in Azure portal

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

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

After successful deployment, you should see your API Management service's private virtual IP address and public virtual IP address on the Overview blade. For more information about the IP addresses, see Routing in this article.

Public and private IP addressed in Azure portal


Since the gateway URL is not registered on the public DNS, the test console available on the Azure portal will not work for an Internal VNET deployed service. Instead, use the test console provided on the Developer portal.

Enable connectivity using a Resource Manager template

API version 2021-01-01-preview (stv2 platform)

API version 2020-12-01 (stv1 platform)

Enable connectivity using Azure PowerShell cmdlets (stv1 platform)

Create or update an API Management instance in a VNET.

DNS configuration

In external VNET mode, Azure manages the DNS. For internal VNET mode, you have to manage your own DNS. We recommend:

  1. Configure an Azure DNS private zone.
  2. Link the Azure DNS private zone to the VNET into which you've deployed your API Management service.

Learn how to set up a private zone in Azure DNS.


The API Management service does not listen to requests on its IP addresses. It only responds to requests to the host name configured on its service endpoints. These endpoints include:

  • API gateway
  • The Azure portal
  • The developer portal
  • Direct management endpoint
  • Git

Access on default host names

When you create an API Management service (contosointernalvnet, for example), the following service endpoints are configured by default:

Endpoint Endpoint configuration
API Gateway
Developer portal
The new developer portal
Direct management endpoint

To access these API Management service endpoints, you can create a virtual machine in a subnet connected to the VNET in which API Management is deployed. Assuming the internal virtual IP address for your service is, you can map the hosts file as follows. On Windows, this file is at %SystemDrive%\drivers\etc\hosts.

Internal virtual IP address Endpoint configuration

You can then access all the service endpoints from the virtual machine you created.

If you use a custom DNS server in a VNET, you can also create DNS A-records and access these endpoints from anywhere in your VNET.

Access on custom domain names

If you don't want to access the API Management service with the default host names:

  1. Set up custom domain names for all your service endpoints, as shown in the following image:

    Set up custom domain name

  2. Create records in your DNS server to access the endpoints accessible from within your VNET.


The following virtual IP addresses are configured for an API Management instance in an internal virtual network. Learn more about the IP addresses of API Management.

Virtual IP address Description
Private virtual IP address A load balanced IP address from within the API Management instance's subnet range (DIP), over which you can access the API gateway, developer portal, management, and Git endpoints.

Register this address with the DNS servers used by the VNET.
Public virtual IP address Used only for control plane traffic to the management endpoint over port 3443. Can be locked down to the ApiManagement service tag.

The load-balanced public and private IP addresses can be found on the Overview blade in the Azure portal.


The VIP address(es) of the API Management instance will change when:

  • The VNET is enabled or disabled.
  • API Management is moved from External to Internal virtual network mode, or vice versa.
  • Zone redundancy settings are enabled, updated, or disabled in a location for your instance (Premium SKU only).

You may need to update DNS registrations, routing rules, and IP restriction lists within the VNET.

VIP and DIP addresses

DIP addresses will be assigned to each underlying virtual machine in the service and used to access resources within the VNET. A VIP address will be used to access resources outside the VNET. If IP restriction lists secure resources within the VNET, you must specify the entire subnet range where the API Management service is deployed to grant or restrict access from the service.

Learn more about the recommended subnet size.


if you deploy 1 capacity unit of API Management in the Premium tier in an internal VNET, 3 IP addresses will be used: 1 for the private VIP and one each for the DIPs for two VMs. If you scale out to 4 units, more IPs will be consumed for additional DIPs from the subnet.

If the destination endpoint has allow-listed only a fixed set of DIPs, connection failures will result if you add new units in the future. For this reason and since the subnet is entirely in your control, we recommend allow-listing the entire subnet in the backend.

Next steps

Learn more about: