Freshness, in progress.

TimShererWithAquent · TimShererWithAquent · commit 7df9d4ebb8ce · 2026-01-27T15:43:33.000-08:00
diff --git a/articles/api-management/api-management-howto-mutual-certificates-for-clients.md b/articles/api-management/api-management-howto-mutual-certificates-for-clients.md
@@ -20,9 +20,9 @@ ms.custom:
 
 API Management provides the capability to secure access to APIs (that is, client to API Management) using client certificates and mutual TLS authentication. You can validate certificates presented by the connecting client and check certificate properties against desired values using policy expressions.
 
-For information about securing access to the backend service of an API using client certificates (that is, API Management to backend), see [How to secure back-end services using client certificate authentication](./api-management-howto-mutual-certificates.md).
+For information about securing access to the backend service of an API using client certificates or API Management to backend, see [Secure backend services](./api-management-howto-mutual-certificates.md).
 
-For a conceptual overview of API authorization, see [Authentication and authorization to APIs in API Management](authentication-authorization-overview.md). 
+For a conceptual overview of API authorization, see [Authentication and authorization](authentication-authorization-overview.md). 
 
 ## Certificate options
 
@@ -41,13 +41,13 @@ Using key vault certificates is recommended because it helps improve API Managem
 
 ## Prerequisites
 
-* If you have not created an API Management service instance yet, see [Create an API Management service instance](get-started-create-service-instance.md).
+* If you haven't created an API Management service instance yet, see [Create an API Management service instance](get-started-create-service-instance.md).
 * You need access to the certificate and the password for management in an Azure key vault or upload to the API Management service. The certificate must be in either CER or PFX format. Self-signed certificates are allowed. 
 
     If you use a self-signed certificate, also install trusted root and intermediate [CA certificates](api-management-howto-ca-certificates.md) in your API Management instance.
     
     > [!NOTE]
-    > CA certificates for certificate validation are not supported in the Consumption tier.
+    > CA certificates for certificate validation aren't supported in the Consumption tier.
 
 [!INCLUDE [api-management-client-certificate-key-vault](../../includes/api-management-client-certificate-key-vault.md)]
 
@@ -58,14 +58,14 @@ Using key vault certificates is recommended because it helps improve API Managem
 
 ### Developer, Basic, Standard, or Premium tier
 
-To receive and verify client certificates over HTTP/2 in the Developer, Basic, Standard, or Premium tiers, you must enable the **Negotiate client certificate** setting on the **Custom domain** blade as shown below.
+To receive and verify client certificates over HTTP/2 in the Developer, Basic, Standard, or Premium tiers, you must enable the **Negotiate client certificate** setting for **Custom domains**.
 
-![Negotiate client certificate](./media/api-management-howto-mutual-certificates-for-clients/negotiate-client-certificate.png)
+:::image type="content" source="./media/api-management-howto-mutual-certificates-for-clients/negotiate-client-certificate.png" alt-text="Screenshot shows the negotiate client certificate option for a custom domain.":::
 
 ### Consumption, Basic v2, Standard v2, or Premium v2 tier
-To receive and verify client certificates in the Consumption, Basic v2, Standard v2, or Premium v2 tier, you must enable the **Request client certificate** setting on the **Custom domains** blade as shown below.
+To receive and verify client certificates in the Consumption, Basic v2, Standard v2, or Premium v2 tier, you must enable the **Request client certificate** setting for **Custom domains**.
 
-![Request client certificate](./media/api-management-howto-mutual-certificates-for-clients/request-client-certificate.png)
+:::image type="content" source="./media/api-management-howto-mutual-certificates-for-clients/request-client-certificate.png" alt-text="Screenshot shows the option to request client certificate for custom domains.":::
 
 ## Policy to validate client certificates
 
@@ -78,12 +78,12 @@ Configure the policy to validate one or more attributes including certificate is
 You can also create policy expressions with the [`context` variable](api-management-policy-expressions.md#ContextVariables) to check client certificates. Examples in the following sections show expressions using the `context.Request.Certificate` property and other `context` properties.
 
 > [!NOTE]
-> Mutual certificate authentication might not function correctly when the API Management gateway endpoint is exposed through the Application Gateway. This is because Application Gateway functions as a Layer 7 load balancer, establishing a distinct SSL connection with the backend API Management service. Consequently, the certificate attached by the client in the initial HTTP request will not be forwarded to APIM. However, as a workaround, you can transmit the certificate using the server variables option. For detailed instructions, refer to [Mutual Authentication Server Variables](../application-gateway/rewrite-http-headers-url.md#mutual-authentication-server-variables).
+> Mutual certificate authentication might not function correctly when the API Management gateway endpoint is exposed through the Application Gateway. The Application Gateway functions as a Layer 7 load balancer, establishing a distinct TLS connection with the backend API Management service. The certificate attached by the client in the initial HTTP request isn't forwarded to APIM. However, as a workaround, you can transmit the certificate using the server variables option. For detailed instructions, refer to [Mutual Authentication Server Variables](../application-gateway/rewrite-http-headers-url.md#mutual-authentication-server-variables).
 
 > [!IMPORTANT]
 > * Starting May 2021, the `context.Request.Certificate` property only requests the certificate when the API Management instance's [`hostnameConfiguration`](/rest/api/apimanagement/current-ga/api-management-service/create-or-update#hostnameconfiguration) sets the `negotiateClientCertificate` property to True. By default, `negotiateClientCertificate` is set to False.
-> * If TLS renegotiation is disabled in your client, you may see TLS errors when requesting the certificate using the `context.Request.Certificate` property. If this occurs, enable TLS renegotiation settings in the client. 
-> * Certification renegotiation is not supported in the API Management v2 tiers.
+> * If TLS renegotiation is disabled in your client, you might see TLS errors when requesting the certificate using the `context.Request.Certificate` property. If the errors appear, enable TLS renegotiation settings in the client. 
+> * Certification renegotiation isn't supported in the API Management v2 tiers.
 
 ### Checking the issuer and subject
 
@@ -101,7 +101,8 @@ Below policies can be configured to check the issuer and subject of a client cer
 
 > [!NOTE]
 > To disable checking certificate revocation list, use `context.Request.Certificate.VerifyNoRevocation()` instead of `context.Request.Certificate.Verify()`.
-> If client certificate is self-signed, root (or intermediate) CA certificate(s) must be [uploaded](api-management-howto-ca-certificates.md) to API Management for `context.Request.Certificate.Verify()` and `context.Request.Certificate.VerifyNoRevocation()` to work.
+>
+> If client certificate is self-signed, root (or intermediate) CA certificates must be [uploaded](api-management-howto-ca-certificates.md) to API Management for `context.Request.Certificate.Verify()` and `context.Request.Certificate.VerifyNoRevocation()` to work.
 
 ### Checking the thumbprint
 
@@ -119,7 +120,7 @@ Below policies can be configured to check the thumbprint of a client certificate
 
 > [!NOTE]
 > To disable checking certificate revocation list, use `context.Request.Certificate.VerifyNoRevocation()` instead of `context.Request.Certificate.Verify()`.
-> If client certificate is self-signed, root (or intermediate) CA certificate(s) must be [uploaded](api-management-howto-ca-certificates.md) to API Management for `context.Request.Certificate.Verify()` and `context.Request.Certificate.VerifyNoRevocation()` to work.
+> If client certificate is self-signed, root (or intermediate) CA certificates must be [uploaded](api-management-howto-ca-certificates.md) to API Management for `context.Request.Certificate.Verify()` and `context.Request.Certificate.VerifyNoRevocation()` to work.
 
 ### Checking a thumbprint against certificates uploaded to API Management
 
@@ -138,14 +139,16 @@ The following example shows how to check the thumbprint of a client certificate
 
 > [!NOTE]
 > To disable checking certificate revocation list, use `context.Request.Certificate.VerifyNoRevocation()` instead of `context.Request.Certificate.Verify()`.
-> If client certificate is self-signed, root (or intermediate) CA certificate(s) must be [uploaded](api-management-howto-ca-certificates.md) to API Management for `context.Request.Certificate.Verify()` and `context.Request.Certificate.VerifyNoRevocation()` to work.
+>
+> If client certificate is self-signed, root (or intermediate) CA certificates must be [uploaded](api-management-howto-ca-certificates.md) to API Management for `context.Request.Certificate.Verify()` and `context.Request.Certificate.VerifyNoRevocation()` to work.
 
 > [!TIP]
-> Client certificate deadlock issue described in this [article](https://techcommunity.microsoft.com/t5/Networking-Blog/HTTPS-Client-Certificate-Request-freezes-when-the-Server-is/ba-p/339672) can manifest itself in several ways, e.g. requests freeze, requests result in `403 Forbidden` status code after timing out, `context.Request.Certificate` is `null`. This problem usually affects `POST` and `PUT` requests with content length of approximately 60KB or larger.
-> To prevent this issue from occurring turn on "Negotiate client certificate" setting for desired hostnames on the "Custom domains" blade as shown in the first image of this document. This feature is not available in the Consumption tier.
+> Client certificate deadlock issue described in this [article](https://techcommunity.microsoft.com/t5/Networking-Blog/HTTPS-Client-Certificate-Request-freezes-when-the-Server-is/ba-p/339672) can manifest itself in several ways, for example, requests freeze, requests result in `403 Forbidden` status code after timing out, `context.Request.Certificate` is `null`. This problem usually affects `POST` and `PUT` requests with content length of approximately 60KB or larger.
+>
+> To prevent this issue from occurring, turn on "Negotiate client certificate" setting for desired hostnames for "Custom domains" as shown in the first image of this document. This feature isn't available in the Consumption tier.
 
 ## Related content
 
--   [How to secure backend services using client certificate authentication](./api-management-howto-mutual-certificates.md)
--   [How to add a custom CA certificate in Azure API Management](./api-management-howto-ca-certificates.md)
--   Learn about [policies in API Management](api-management-howto-policies.md)
+- [Secure backend services in Azure API Management](./api-management-howto-mutual-certificates.md)
+- [How to add a custom CA certificate in Azure API Management](./api-management-howto-ca-certificates.md)
+- [Policies in Azure API Management](api-management-howto-policies.md)
diff --git a/includes/api-management-client-certificate-key-vault.md b/includes/api-management-client-certificate-key-vault.md
@@ -10,7 +10,6 @@ ms.custom: sfi-image-nochange
 ### Prerequisites for key vault integration
 
 1. If you don't already have a key vault, create one. For information about creating a key vault, see [Quickstart: Create a key vault using the Azure portal](/azure/key-vault/general/quick-create-portal).
-
     
 1. Enable a system-assigned or user-assigned [managed identity](../articles/api-management/api-management-howto-use-managed-service-identity.md) in API Management.
 
@@ -38,14 +37,20 @@ To add a key vault certificate to API Management:
 1. In **Id**, enter a name.
 1. In **Certificate**, select **Key vault**.
 1. Enter the identifier of a key vault certificate, or choose **Select** to select a certificate from a key vault.
-    > [!IMPORTANT]
-    > If you enter a key vault certificate identifier yourself, be sure that it doesn't have version information. Otherwise, the certificate won't rotate automatically in API Management after an update in the key vault.
+
+   > [!IMPORTANT]
+   >
+   > If you enter a key vault certificate identifier yourself, be sure that it doesn't have version information. Otherwise, the certificate won't rotate automatically in API Management after an update in the key vault.
+
 1. In **Client identity**, select a system-assigned identity or an existing user-assigned managed identity. For more information, see [Use managed identities in Azure API Management](../articles/api-management/api-management-howto-use-managed-service-identity.md).
-    > [!NOTE]
-    > The identity needs to have permissions to get and list certificates from the key vault. If you haven't already configured access to the key vault, API Management prompts you so that it can automatically configure the identity with the necessary permissions.
+
+   > [!NOTE]
+   >
+   > The identity needs to have permissions to get and list certificates from the key vault. If you haven't already configured access to the key vault, API Management prompts you so that it can automatically configure the identity with the necessary permissions.
+
 1. Select **Add**.
 
-    :::image type="content" source="../articles/api-management/media/api-management-howto-mutual-certificates/apim-client-cert-kv.png" alt-text="Screenshot that shows how to add a key vault certificate to API Management in the portal." lightbox="../articles/api-management/media/api-management-howto-mutual-certificates/apim-client-cert-kv.png":::
+   :::image type="content" source="../articles/api-management/media/api-management-howto-mutual-certificates/apim-client-cert-kv.png" alt-text="Screenshot that shows how to add a key vault certificate to API Management in the portal." lightbox="../articles/api-management/media/api-management-howto-mutual-certificates/apim-client-cert-kv.png":::
     
 1. Select **Save**.
 
@@ -61,7 +66,6 @@ To upload a client certificate to API Management:
 1. Browse to select the certificate .pfx file, and enter its password.
 1. Select **Add**.
 
-    :::image type="content" source="../articles/api-management/media/api-management-howto-mutual-certificates/apim-client-cert-add.png" alt-text="Screenshot of uploading a client certificate to API Management in the portal.":::
-
+   :::image type="content" source="../articles/api-management/media/api-management-howto-mutual-certificates/apim-client-cert-add.png" alt-text="Screenshot of uploading a client certificate to API Management in the portal.":::
 
 1. Select **Save**.
diff --git a/includes/api-management-key-vault-access.md b/includes/api-management-key-vault-access.md
@@ -2,14 +2,14 @@
 author: dlepow
 ms.service: azure-api-management
 ms.topic: include
-ms.date: 01/11/2023
+ms.date: 01/29/2026
 ms.author: danlep
 ---
 
 ### Configure access to key vault
 
-1. In the portal, go to your key vault.
-1. In the left menu, select **Settings** > **Access configuration**. Note the **Permission model** that's configured.
+1. In the Azure portal, go to your key vault.
+1. In the left menu, select **Settings** > **Access configuration**. Make a note of the configured **Permission model**.
 1. Depending on the permission model, configure either a [key vault access policy](/azure/key-vault/general/assign-access-policy) or [Azure RBAC access](/azure/key-vault/general/rbac-guide) for an API Management managed identity.
     
 **To add a key vault access policy:**
diff --git a/includes/api-management-key-vault-network.md b/includes/api-management-key-vault-network.md
@@ -2,7 +2,7 @@
 author: dlepow
 ms.service: azure-api-management
 ms.topic: include
-ms.date: 12/18/2025
+ms.date: 01/29/2026
 ms.author: danlep
 ---
 
@@ -15,18 +15,18 @@ If [Key Vault firewall](/azure/key-vault/general/network-security) is enabled on
 
 * In Key Vault firewall, enable the **Allow Trusted Microsoft Services to bypass this firewall** option. API Management supports trusted service connectivity to access the key vault for control-plane options.
 
-* Ensure that your local client IP address is allowed to access the key vault temporarily while you select a certificate or secret to add to Azure API Management. For more information, see [Configure Azure Key Vault networking settings](/azure/key-vault/general/how-to-azure-key-vault-network-security).
+* Ensure that your local client IP address is allowed to access the key vault temporarily. You must select a certificate or secret to add to Azure API Management. For more information, see [Configure Azure Key Vault networking settings](/azure/key-vault/general/how-to-azure-key-vault-network-security).
 
     After completing the configuration, you can block your client address in the key vault firewall.
 
 > [!IMPORTANT]
-> Starting March 2026, trusted service connectivity to Azure services from the API Management gateway by enabling the **Allow Trusted Microsoft Services to bypass this firewall** firewall setting will no longer be supported. To continue accessing these services from the API Management gateway after this change, ensure that you choose a different supported network access option. For control-plane operations, you can continue to use trusted service connectivity. [Learn more](../articles/api-management/breaking-changes/trusted-service-connectivity-retirement-march-2026.md).
+> Starting March 2026, trusted service connectivity to Azure services from the API Management gateway by enabling the **Allow Trusted Microsoft Services to bypass this firewall** firewall setting aren't supported. To continue accessing these services from the API Management gateway after this change, ensure that you choose a different supported network access option. For control-plane operations, you can continue to use trusted service connectivity. [Learn more](../articles/api-management/breaking-changes/trusted-service-connectivity-retirement-march-2026.md).
 
 #### Virtual network requirements
 
 If the API Management instance is deployed in a virtual network, also configure the following network settings:
 
 * Enable a [service endpoint](/azure/key-vault/general/overview-vnet-service-endpoints) to Key Vault on the API Management subnet.
-* Configure a network security group (NSG) rule to allow outbound traffic to the AzureKeyVault and AzureActiveDirectory [service tags](../articles/virtual-network/service-tags-overview.md).
+* Configure a network security group (NSG) rule to allow outbound traffic to the `AzureKeyVault` and `AzureActiveDirectory` [service tags](../articles/virtual-network/service-tags-overview.md).
 
 For details, see [Network configuration when setting up API Management in a virtual network](../articles/api-management/virtual-network-reference.md).
