Configure a custom domain name

When you provision a self-hosted Azure API Management gateway it is not assigned host name and has to be referenced by its IP address. This article shows how to map an existing custom DNS name (also referred to as hostname) a self-hosted gateway.


Self-hosted gateway feature is in preview. During the preview, the self-hosted gateway is available only in the Developer and Premium tiers at no additional charge. Developer tier is limited to a single self-hosted gateway deployment.


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

  • An active Azure subscription.

    If you don't have an Azure subscription, create a free account before you begin.

  • An API Management instance. For more information, see Create an Azure API Management instance.

  • A self-hosted gateway. For more information, see How to provision self-hosted gateway

  • A custom domain name that is owned by you or your organization. This topic does not provide instructions on how to procure a custom domain name.

  • A DNS record hosted on a DNS server that maps the custom domain name to the self-hosted gateway's IP address. This topic does not provide instructions on how to host a DNS record.

  • You must have a valid certificate with a public and private key (.PFX). Subject or subject alternative name (SAN) has to match the domain name (this enables API Management instance to securely expose URLs over SSL).

Go to your API Management instance

  1. In the Azure portal, search for and select API Management services.

    Select API Management services

  2. On the API Management screen, select your API Management instance.

    Select your API Management instance

Add custom domain certificate to your API Management service

  1. Select Certificates from under Security.
  2. Select + Add.
  3. Enter a resource name for the certificate into Id field.
  4. Select the file containing the certificate (.PFX) by selecting the Certificate field or the folder icon adjacent to it.
  5. Enter the password for the certificate into the Password field.
  6. Select Create to add the certificate to your API Management service.

Use the Azure portal to set a custom domain name for your self-hosted gateway

  1. Select the Gateways from under Settings.
  2. Select the self-hosted gateway you want to configure the domain name for.
  3. Select Hostnames under Settings.
  4. Select + Add
  5. Enter resource name for the hostname into the Name field.
  6. Enter domain name in the Hostname field.
  7. Select a certificate from the Certificate dropdown.
  8. Select Negotiate client certificate checkbox if any of the APIs exposed via this gateway use client certificate authentication.


    This setting is shared by all domain names configured for the gateway.

  9. Select Add to assign the custom domain name to the selected self-hosted gateway.

Next steps

Upgrade and scale your service