Send Docs Feedback

Note: Most user interface tasks can be performed in Edge Classic or the New Edge experience. For an overview, getting started topics, and release notes specific to the New Edge experience, see the docs.

Configuring TLS access to an API for the Cloud

Self-service TLS/SSL Beta: For details, see self-service TLS/SSL Beta release.

Configuring TLS access to your APIs typically requires that you make a request to Apigee Customer Support to create a virtual host on Edge. For more on virtual hosts, see About virtual hosts (Beta).

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

Using the default virtual hosts

For a cloud based version of Edge, Apigee automatically 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.

These virtual hosts let you get started building your APIs without having to contact Apigee to create any additional virtual hosts.

Apigee provides an TLS 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.


All Apigee Cloud customers use the same Apigee-provided cert. Therefore, if you are a Cloud customer and are doing two-way TLS to the backend, you should not use the Apigee-provided cert because it cannot be used to uniquely identify the owner of the API proxy connecting to the backend. 

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:





While you typically work with Apigee to create virtual hosts that use your own domain name, rather than use the default "" domain, you can continue to use the ones from Apigee as well. Just configure your own CNAME to alias these default virtual hosts.

What you need to provide to Apigee to create a virtual host

To create a virtual host that uses the unencrypted HTTP protocol, you do not need any information before contacting Apigee.

If you want to configure an encrypted virtual host that uses TLS over HTTPS, then you need the following:

  • TLS certificate as a PEM file - either a certificate signed by a certificate authority (CA), or a chain of certificates where the last certificate is signed by a CA.
  • Private key as a PEM file. Edge supports key sizes up to 2048 bits. A passphrase is optional.

Once you have the TLS cert and private key, create a keystore and upload the cert/key pair to the keystore. See Keystores and Truststores.

If you want to create two-way TLS then, depending on how you configure two-way TLS, you might also need to create a truststore for that certificate to enable two-way TLS with the client. See Keystores and Truststores.

After Apigee Customer Support creates the virtual host, they return to you the CNAME used to access your virtual host. It is then up to you to create a DNS record for your domain, for example, that references the CNAME.

Updating API proxies to use the new virtual host

An API proxy can be accessed over all virtual hosts referenced in its ProxyEndpoint definition. After Apigee notifies you that your new virtual host has been created, any new API proxies that you create automatically reference the virtual host and any other existing virtual hosts, including the default virtual hosts provided by Apigee. 

However, if you created any API proxies before requesting the virtual host, then you must edit the API proxy to explicitly add the new virtual host to its ProxyEndpoint. Otherwise, the API proxy is not accessible over the virtual host.

All virtual hosts are automatically added to all new API proxies. Therefore, 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.

For more, see Updating an API proxy after creating a virtual host in About virtual hosts (Beta).

Help or comments?