| title | Configure custom domain name for Azure API Management instance | |||
|---|---|---|---|---|
| titleSuffix | Azure API Management | |||
| description | How to configure a custom domain name and choose certificates for the endpoints of your Azure API Management instance. | |||
| services | api-management | |||
| author | dlepow | |||
| ms.service | azure-api-management | |||
| ms.topic | how-to | |||
| ms.date | 04/03/2026 | |||
| ms.author | danlep | |||
| ms.custom |
|
[!INCLUDE api-management-availability-all-tiers]
When you create an Azure API Management service instance in the Azure cloud, Azure assigns it a azure-api.net subdomain (for example, apim-service-name.azure-api.net). You can also expose your API Management endpoints using your own custom domain name, such as contoso.com. This article shows you how to map an existing custom DNS name to endpoints exposed by an API Management instance.
Important
API Management only accepts requests with host header values matching:
- The Gateway's default domain name
- Any of the Gateway's configured custom domain names
Note
Currently, custom domain names aren't supported in a workspace gateway.
[!INCLUDE api-management-service-update-behavior]
-
An API Management instance. For more information, see Create an Azure API Management instance.
-
A custom domain name that is owned by you or your organization. This article does not provide instructions on how to procure a custom domain name.
-
Optionally, a valid certificate with a public and private key (.PFX). The subject or subject alternative name (SAN) has to match the domain name (this enables API Management instance to securely expose URLs over TLS).
-
DNS records hosted on a DNS server to map the custom domain name to the default domain name of your API Management instance. This topic does not provide instructions on how to host the DNS records.
For more information about required records, see DNS configuration, later in this article.
There are several API Management endpoints to which you can assign a custom domain name. Currently, the following endpoints are available:
| Endpoint | Default |
|---|---|
| Gateway | Default is: <apim-service-name>.azure-api.net. Gateway is the only endpoint available for configuration in the Consumption tier.The default Gateway endpoint configuration remains available after a custom Gateway domain is added. |
| Developer portal (all tiers except Consumption) | Default is: <apim-service-name>.developer.azure-api.net |
| Management (classic tiers only) | Default is: <apim-service-name>.management.azure-api.net |
| Self-hosted gateway configuration API (v2) | Default is: <apim-service-name>.configuration.azure-api.net |
| SCM (classic tiers only) | Default is: <apim-service-name>.scm.azure-api.net |
- You can update any of the endpoints supported in your service tier. Typically, customers update Gateway (this URL is used to call the APIs exposed through API Management) and Developer portal (the developer portal URL).
- The default Gateway endpoint remains available after you configure a custom Gateway domain name and cannot be deleted. For other API Management endpoints (such as Developer portal) that you configure with a custom domain name, the default endpoint is no longer available.
- Only API Management instance owners can use Management and SCM endpoints internally. These endpoints are less frequently assigned a custom domain name.
- The Premium and Developer tiers support setting multiple hostnames for the Gateway endpoint.
- Wildcard domain names, like
*.contoso.com, are supported in all tiers except the Consumption tier. A specific subdomain certificate (for example, api.contoso.com) would take precedence over a wildcard certificate (*.contoso.com) for requests to api.contoso.com. - When configuring a custom domain for the Developer portal, you can enable CORS for the new domain name. This is needed for developer portal visitors to use the interactive console in the API reference pages.
API Management supports custom TLS certificates or certificates imported from Azure Key Vault. You can also enable a free, managed certificate.
Warning
If you require certificate pinning, please use a custom domain name and either a custom or Key Vault certificate, not the default certificate or the free, managed certificate. We don't recommend taking a hard dependency on a certificate that you don't manage.
If you already have a private certificate from a third-party provider, you can upload it to your API Management instance. It must meet the following requirements. (If you enable the free certificate managed by API Management, it already meets these requirements.)
- Exported as a PFX file, encrypted using triple DES, and optionally password protected.
- Contains private key at least 2048 bits long
- Contains all intermediate certificates and the root certificate in the certificate chain.
We recommend using Azure Key Vault to manage your certificates and setting them to autorenew.
If you use Azure Key Vault to manage a custom domain TLS certificate, make sure the certificate is inserted into Key Vault as a certificate, not a secret.
Caution
When using a key vault certificate in API Management, be careful not to delete the certificate, key vault, or managed identity used to access the key vault.
To fetch a TLS/SSL certificate, API Management must have the list and get secrets permissions on the Azure Key Vault containing the certificate.
-
When you use the Azure portal to import the certificate, all the necessary configuration steps are completed automatically.
-
When you use command-line tools or management API, these permissions must be granted manually, in two steps:
- On the Managed identities page of your API Management instance, enable a system-assigned or user-assigned managed identity. Note the principal ID on that page.
- Assign permissions to the managed identity to access the key vault. Use steps in the following section.
[!INCLUDE api-management-key-vault-certificate-access]
If the certificate is set to autorenew and your API Management tier has an SLA (that is, in all tiers except the Developer tier), API Management will pick up the latest version automatically, without downtime to the service.
For more information, see Use managed identities in Azure API Management.
API Management offers a free, managed TLS certificate for your domain, if you don't wish to purchase and manage your own certificate. The certificate is autorenewed automatically.
Important
Creation of managed certificates for custom domains in API Management will be temporarily unavailable from August 15, 2025 to June 30, 2026. Our Certificate Authority (CA), DigiCert, will migrate to a new validation platform to meet Multi-Perspective Issuance Corroboration (MPIC) requirements for issuing certificates. This migration requires us to temporarily suspend the creation of managed certificates for custom domains. Learn more
Existing managed certificates will be autorenewed and remain unaffected.
While creation of managed certificates is suspended, use other certificate options for configuring custom domains.
Note
The free, managed TLS certificate is in preview.
- Currently can be used only with the Gateway endpoint of your API Management service
- Not supported in the v2 tiers
- Not supported with the self-hosted gateway
- Not supported in the following Azure regions: France South and South Africa West
- Currently available only in the Azure cloud
- Does not support root domain names (for example,
contoso.com). Requires a fully qualified name such asapi.contoso.com. - Supports only public domain names
- Can only be configured when updating an existing API Management instance, not when creating an instance
[!INCLUDE api-management-managed-certificate-ip-access.md]
Choose the steps according to the domain certificate you want to use.
- Navigate to your API Management instance in the Azure portal.
- In the left navigation, select Custom domains.
- Select +Add, or select an existing endpoint that you want to update.
- In the window on the right, select the Type of endpoint for the custom domain.
- In the Hostname field, specify the name you want to use. For example,
api.contoso.com. - Under Certificate, select Custom
- Select Certificate file to select and upload a certificate.
- Upload a valid .PFX file and provide its Password, if the certificate is protected with a password.
- When configuring a Gateway endpoint, select or deselect other options as necessary, including Negotiate client certificate or Default SSL binding. :::image type="content" source="media/configure-custom-domain/gateway-domain-custom-certificate.png" alt-text="Configure gateway domain with custom certificate":::
- Select Add, or select Update for an existing endpoint.
- Select Save.
- Navigate to your API Management instance in the Azure portal.
- In the left navigation, select Custom domains.
- Select +Add, or select an existing endpoint that you want to update.
- In the window on the right, select the Type of endpoint for the custom domain.
- In the Hostname field, specify the name you want to use. For example,
api.contoso.com. - Under Certificate, select Key Vault and then Select.
- Select the Subscription from the dropdown list.
- Select the Key vault from the dropdown list.
- Once the certificates have loaded, select the Certificate from the dropdown list. Click Select.
- In Client identity, select a system-assigned identity or a user-assigned managed identity enabled in the instance to access the key vault.
- When configuring a Gateway endpoint, select or deselect other options as necessary, including Negotiate client certificate or Default SSL binding. :::image type="content" source="media/configure-custom-domain/gateway-domain-key-vault-certificate.png" alt-text="Configure gateway domain with Key Vault certificate":::
- Select Add, or select Update for an existing endpoint.
- Select Save.
- Navigate to your API Management instance in the Azure portal.
- In the left navigation, select Custom domains.
- Select +Add, or select an existing endpoint that you want to update.
- In the window on the right, select the Type of endpoint for the custom domain.
- In the Hostname field, specify the name you want to use. For example,
api.contoso.com. - Under Certificate, select Managed to enable a free certificate managed by API Management. The managed certificate is available in preview for the Gateway endpoint only.
- Copy the following values and use them to configure DNS:
- TXT record
- CNAME record
- When configuring a Gateway endpoint, select or deselect other options as necessary, including Negotiate client certificate or Default SSL binding. :::image type="content" source="media/configure-custom-domain/gateway-domain-free-certifcate.png" alt-text="Configure gateway domain with free certificate":::
- Select Add, or select Update for an existing endpoint.
- Select Save.
Configure your DNS provider to map your custom domain name to the default domain name of your API Management instance.
[!INCLUDE api-management-custom-domain-dns-configuration.md]
[!INCLUDE api-management-custom-domain-dns-configuration.md]
[!INCLUDE api-management-custom-domain-dns-configuration.md]
Caution
When you use the free, managed certificate and configure a CNAME record with your DNS provider, make sure that it resolves to the default API Management service hostname (<apim-service-name>.azure-api.net). Currently, API Management doesn't automatically renew the certificate if the CNAME record doesn't resolve to the default API Management hostname. For example, if you're using the free, managed certificate and you use Cloudflare as your DNS provider, make sure that DNS proxy isn't enabled on the CNAME record.
When enabling the free, managed certificate for API Management, also configure a TXT record in your DNS zone to establish your ownership of the domain name.
- The name of the record is your custom domain name prefixed by
apimuid. Example:apimuid.api.contoso.com. - The value is a domain ownership identifier provided by your API Management instance.
When you use the portal to configure the free, managed certificate for your custom domain, the name and value of the necessary TXT record are automatically displayed.
You can also get a domain ownership identifier by calling the Get Domain Ownership Identifier REST API.
[!INCLUDE api-management-custom-domain]
[!INCLUDE api-management-standard-v2-limitation]
Because of a configuration change or connectivity problem, your API Management instance might be unable to fetch a hostname certificate from Azure Key Vault after a certificate is updated or rotated there. When this happens, your API Management instance continues to use a cached certificate until it receives an updated certificate. If the cached certificate expires, runtime traffic to the gateway will be blocked. Any upstream service such as Application Gateway that uses the hostname certificate configuration could also block runtime traffic to the gateway when an expired cached certificate is used.
To mitigate this problem, confirm that the key vault exists, and the certificate is stored in the key vault. If your API Management instance is deployed in a virtual network, confirm outbound connectivity to the AzureKeyVault service tag. Check whether the managed identity used to access the key vault exists. Confirm the managed identity's permissions to access the key vault. Review Set up a custom domain name - Key Vault, earlier in this article, for detailed configuration steps. After the configuration is restored, the hostname certificate will refresh in API Management within 4 hours.