Send Docs Feedback

Virtual hosts

About virtual hosts

Virtual hosts are the base URLs of an API proxy. They include the protocol (http or https), along with the hostname of the API proxy, which maps to a router address and port through DNS.

In Edge, a virtual host is identified by a name. By default, when you first create an Edge organization, you get two virtual hosts in each environment:

  • default - http://[org]-[environment] (port 80)
  • secure - https://[org]-[environment] (port 443)

You can see your virtual hosts in the Build a Proxy wizard as you create a new API proxy, in the management UI by going to APIs > Environment Configuration > Virtual Hosts, and with the List Virtual Hosts and Get Virtual Host management APIs.

In the XML configuration of an API proxy, the virtual host is specified by name. For example, <VirtualHost>secure</VirtualHost> means a client can call the API proxy using the base URL of the "secure" virtual host; for example,

One of the main uses of virtual hosts is to let you customize the domain name of your APIs hosted on Edge. For example, on a cloud-based version of Edge, the default domain name of an organization called "myorg" in the prod environment is "". Therefore, to access an API in that organization, a developer uses a URL in the form:{proxy-base-path}/{resource-path}

However, a domain name containing "" may not be what you want to expose to your customers. A virtual host can map your own domain name to your organization on Edge, letting developers access your API through a domain specific to your company, for example:{proxy-base-path}/{resource-path}

Note that creating a virtual host does not also make the domain name accessible. You must still create a DNS record for the domain.

Learn more:

About virtual hosts on a cloud-based Edge installation

After you create an API proxy on Edge, you can make that API available for requests. However, the first thing you need to determine is the complete URL of the resources accessed through the API proxy. That URL has the form:




  • {org-name} is your organization name.
  • {env-name} is the environment name. By default, all Apigee organizations created in the cloud are provisioned with two environments: 'test' and 'prod'. When deploying an API proxy, you can choose to deploy it to one or both environments.
  • {proxy-base-path} defined when you create an API proxy.
  • {resource-path} the path to a resource accessible through the API proxy.

The domain name of the URL and the HTTP or HTTPS access protocol is defined by a virtual host on Edge. By default, Apigee creates two virtual hosts for every environment in an organization:

  • default: Defines HTTP access to your APIs on port 80.
  • secure: Defines HTTPS access to your APIs on port 443.

Apigee provides an TLS/SSL certificate and private key to support HTTPS on the secure virtual host so that you can quickly get started developing and testing your APIs. While many customers prefer to use their own certificate and private key at deployment time, you can deploy your APIs using the Apigee cert and key.

Apigee also creates DNS records for each virtual host. Therefore, you can use any or all of the following four URLs to access your API:





About virtual hosts on Edge for Private Cloud (on-premises)

When you install Apigee Edge for Private Cloud, there are no default organizations, environments, or virtual hosts created for you. After you complete the Edge installation process, your first action is typically to create an organization, environment, and virtual host through the "onboarding" process.

To perform onboarding, run the following command on the Edge Management Server node:

/<inst_root>/apigee/apigee-service/bin/apigee-service apigee-provision setup-org -f configFile

where <inst_root> is the root directory of your Edge installation, and configFile contains the information necessary to create a user, organization, environment, and virtual host.

For example, you create:

  • A user of your choosing to function as the organization administrator
  • An organization named example
  • An environment in the organization named prod
  • A virtual host in the environment named default that allows HTTP access on port 9001
  • A host alias of the DNS name used to access the Router, or the IP address of the Router and port of the virtual host in the form IP:9001.

As of Edge for Private Cloud version 4.16.01, you must specify a host alias when creating a virtual host. In releases previous to 4.16.01, the host alias was optional.


Also, the combination of host alias name and port number for the virtual host must be unique for all virtual hosts in the Edge installation.

After running the onboarding script, you can later add any number of organizations, environments, and virtual hosts to your on-premises version of Edge. For more information, see the Apigee Edge for Private Cloud Operations Guide.

Virtual hosts are opened on the Edge Router node. Therefore, you have to ensure that the port that you specify for the virtual host is open on the Router node. You can use a command in the form below to open a port:

$ iptables -A INPUT -m state --state NEW -m tcp -p tcp --dport 9001 -j ACCEPT --verbose 

After running that script, you can access your APIs by using a URL in the form:


Note that this URL uses the IP address of the Router and the virtual host port on the Router to access your APIs. Typically, you do not publish your APIs to customers with an IP address and port number. Instead, you define a DNS entry for the router and port. For example:{proxy-base-path}/{resource-path}

If you define the DNS entry, then you also must create a host alias for the virtual host that matches the domain name of the DNS entry. From the example above, you would specify a host alias of when you create the virtual host.

Note also that the URL uses the HTTP protocol. To use the encrypted HTTPS protocol, you must create a virtual host that references a keystore. A keystore contains the certificate and private key required to support HTTPS. For more, see Configuring TLS access to an API for the Private Cloud.

Viewing information about a virtual host

You can use the Edge management UI to see the virtual hosts defined in an environment:

  1. Login to the Edge management UI at (cloud) or http://<ms-ip>:9000 (on-premises), where <ms-ip> is the IP address of the Management Server node.
  2. In the Edge management UI menu, select APIs > Environment Configuration.
  3. Select the environment, such as prod or test. The virtual hosts defined for the environment appear.
  4. Go to the Virtual Hosts tab.

    If the virtual host is configured to use a keystore or truststore, select the Show button to see more information.

You can also use the Edge APIs to view information about virtual hosts. For example, the List Virtual Hosts API returns a list of all virtual hosts:

$ curl -X GET -H "accept:application/xml" \{org}/environments/{env}/virtualhosts \
-u email:password

Sample response:


To see information about a specific virtual host, use the Get Virtual Host API:

$ curl -X GET -H "accept:application/xml" \{org_name}/environments/{env_name}/virtualhosts/default \
-u email:password

Sample response:

 "hostAliases" : [ ],
 "interfaces" : [ ],
 "name" : "default",
 "port" : "9001"

In Edge for Private Cloud, replace the domain name with <ms-ip>:8080 where <ms-ip> is the IP of the Edge Management Server.

If the virtual host is configured to use TLS/SSL, a lock icon appears next to the name of the virtual host. That means an TLS/SSL certificate, key, and certificate chain has been uploaded to Edge and associated with the virtual host.

To see information about the available certificates:

  1. Login to the Edge management UI.
  2. In the Edge management UI menu, select Admin > SSL Certificates.
  3. Expand the keystores until you see the certificate.

To use the the Get Cert Details from a Keystore or Truststore to view a cert:

$ curl -H 'accept: application/xml' \{org_name}/environments/{env_name}/keystores/freetrial/certs/ \
-u email:password

Creating a virtual host

You can create a virtual host that uses the HTTP protocol or one that uses TLS/SSL and the encrypted HTTPS protocol. The way you create virtual hosts depends on your Edge installation: cloud or Edge for Private Cloud (on-premises).

Creating a virtual host on a cloud-based Edge installation

If you have an Apigee Edge paid plan, Apigee creates virtual hosts for you. For technical and security reasons, virtual host creation and manipulation in Edge cloud accounts is not self-service. For assistance with virtual hosts, contact Apigee Customer Support at

If you want to create a virtual host that supports TLS/SSL, then you must obtains the necessary TLS/SSL certificate and private key. Apigee then uses the cert and key to configure the virtual host.  

See Using TLS in a cloud-based Edge installation for more on creating virtual hosts for a cloud installation.

Creating a virtual host on Edge for Private Cloud

In an on-premises installation, you have complete control over virtual hosts. You can create virtual hosts for any org, in any environments, using TLS/SSL or not.

See Configuring TLS access to an API for the Private Cloud for more on creating virtual hosts for an on-premises installation.

Updating an API proxy after creating a virtual host

An API proxy references the virtual hosts that it supports in its ProxyEndpoint definition. When you create a new API proxy, Edge automatically configures its ProxyEndpoint to use all available virtual hosts.

After Apigee notifies you that your new virtual host has been created for a cloud installation, or after you create one directly in an on-premises installation, any new API proxies that you create automatically reference the virtual host.

If you create a new API proxy that should not be accessible over a particular virtual host, then you must edit the API proxy to remove that virtual host from its ProxyEndpoint.

If you created any API proxies before requesting the virtual host, then you must edit the API proxy to add the new virtual hosts to its ProxyEndpoint. Otherwise, the API proxy is not accessible by the virtual host.

If you are developing your API proxies in XML, edit the XML file for the ProxyEndpoint to add or remove a virtual host.

To use the Edge management UI to edit the ProxyEndpoint:

  1. Login to the Edge management UI at
  2. In the Edge management UI menu, select APIs.
  3. Select the name of the API proxy to update.
  4. Select the Development tab.
  5. Under Proxy Endpoints, select default.
  6. In the code area:
    1. Remove any <VirtualHost> elements for virtual hosts not supported by the API proxy.
    2. Add a new <VirtualHost> element with the name of the new virtual host. For example, if the new virtual host is named MyVirtualHost, add the following tag:

  7. Save the API proxy. If the API proxy has been deployed, saving it redeploys it with the new setting.

Help or comments?