Update Azure API Gateway

Hi @FunMum ,

Updating TLS certificates for an API Management “gateway” can mean a couple different things in APIM (the built-in gateway vs. a self-hosted gateway running your own containers). The “best practice with least disruption” depends on which one you’re using, but here are the APIM-specific angles we can cover from the provided docs.

If you’re using an APIM Self-hosted Gateway

With a self-hosted gateway, Microsoft’s guidance (from the self-hosted gateway overview/support guidance) is that the gateway continuously checks Azure for configuration updates:

• It sends heartbeat/status every minute.
• It checks for and applies configuration updates every 10 seconds (via its management plane connection).
• It requires outbound connectivity to Azure on TCP 443 so it can receive those updates and report status/metrics.

What this implies for “least disruption”:

• Keep the gateway’s outbound connectivity to Azure healthy (TCP 443), because the gateway relies on contacting Azure to pick up configuration changes.
• When you update the TLS material/certificates in the relevant APIM configuration, the self-hosted gateway should fetch/apply the change shortly after (on the order of seconds, per the 10-second config check).

Also note the operational boundary: you (the customer) are responsible for hosting, uptime, diagnostics, and infrastructure for the self-hosted gateway. Microsoft maintains the container image and provides patches, but you handle the runtime environment.

Automation/control plane update mechanism (why disruption can be minimized)

Since the gateway automatically checks for updates every 10 seconds and applies configuration updates whenever they’re available, the practical “best practice” is to:

• Update the certificate configuration in APIM (control plane).
• Ensure the self-hosted gateway still has outbound access to Azure (TCP 443), so it can pull the new config quickly.

If you’re using APIM behind an internal Application Gateway

If your TLS termination/proxy is happening at Application Gateway (common in VNet/internal patterns), the docs emphasize that Application Gateway is configured with:

• Certificates used to decrypt and re-encrypt traffic
• Trusted root configuration for backend certificates
• Backend settings and routing

In that setup, the “least disruption” approach is usually to treat certificate updates as part of the Application Gateway configuration workflow (since that’s what is terminating TLS on the path), rather than relying only on changes inside APIM.

References:

• APIM Self-Hosted Gateway Configuration and Troubleshooting Guidance (includes heartbeat + 10-second config update behavior, and outbound 443 connectivity requirement)
• Self-hosted gateway overview / FQDN dependencies
• Update-AzApiManagementGateway (PowerShell cmdlet reference)
• Integrate API Management in an internal virtual network with Application Gateway (certificate prerequisites and App Gateway TLS/certificate configuration context)

Hope this helps!

If the resolution was helpful, kindly take a moment to click on and click on Yes for was this answer helpful. And, if you have any further query do let us know.

Hello FunMum,

Welcome to Microsoft Q&A,

Updating the TLS certificate on APIM's Gateway endpoint does not cause downtime on its own, except on the Developer tier (no SLA, single unit). On all other tiers, the gateway keeps serving traffic while the certificate update rolls out.

Best practice depends on how your certificate is managed:

If you're using Key Vault (recommended):

1. Store the certificate in Key Vault as a certificate object (not a secret) and set it to autorenew.
2. APIM picks up the renewed version automatically, with no downtime. This can take up to 1-2 days.
3. Don't want to wait? Go to your APIM instance > Custom domains > select Sync certificates on the command bar to force an immediate pickup.
4. If sync fails, use View sync logs on the same command bar to see the root cause (usually a Key Vault access or managed identity permission issue).

Since you're updating the existing endpoint rather than deleting and recreating it, there's no window where the domain has no certificate bound. Just keep in mind infrastructure changes like this can take 15 minutes or longer to fully propagate, more if you're on a multi-region or multi-unit deployment, but the gateway continues serving requests throughout (Developer tier excluded).

One more thing worth checking: if the cert is Key Vault backed and access breaks (deleted identity, vault permission changes), APIM falls back to the last cached certificate until it expires. So don't touch the managed identity or vault permissions while doing this.

Ref:

1. Configure a custom domain name for API Management
2. Certificate synchronization and troubleshooting for Key Vault-backed certificates

Please Upvote and accept the answer if it helps!!