Azure API Management Security: Keys, Tokens, Managed Identity and Gateway Hardening

Azure API Management sits in front of an organisation's APIs and holds the keys to all of them, so a loose subscription key model, a loose JWT policy or an over-privileged policy editor turns the gateway into the easiest way in. API Management (APIM) combines a gateway, a management plane, a developer portal and, optionally, self-hosted gateways that run in your own clusters. Each has its own identities and credentials: subscription keys for callers, Microsoft Entra roles for administrators, managed identities for backend calls, and gateway tokens for self-hosted nodes. This guide explains how those pieces fit together, which settings Microsoft documents as security relevant, and how to log and harden them. It is for cloud security engineers, API platform owners and auditors who run APIM in production. For vendor neutral API controls, see the API Security Guide.

This is an independent guide from NHI Mgmt Group, based on Microsoft's public documentation as of November 2026. It is not sponsored or reviewed by Microsoft. Product features change, so confirm settings against Microsoft's current documentation.

Key takeaways

• Subscription keys identify, they do not authenticate users. Keys have no built-in expiry or automatic rotation, so pair them with validate-jwt or validate-azure-ad-token and rotate the primary and secondary pair on a schedule.
• Policy edit rights are identity rights. Anyone who can write policies can call authentication-managed-identity and obtain the instance's managed identity token, so treat policy write access as privileged.
• Write access exposes stored credentials. Removing listSecrets hides backend and named value secrets from readers, but a principal with write access sees credentials returned in PUT and PATCH responses.
• The all-access subscription is a master key. It grants every API in the instance and bypasses product scope policies; suspend it unless someone needs it for testing.
• Self-hosted gateways carry their own secret. The gateway access token expires at least every 30 days and is backed by a gateway key; prefer Microsoft Entra workload identity on AKS.

How identity and access work in Azure API Management

APIM has three separate trust boundaries, and most incidents come from confusing them. The management plane is governed by Azure RBAC. The data plane (the gateway) decides whether a caller may reach an API, using subscription keys, tokens, client certificates or a combination. The backend boundary decides how APIM proves itself to the services behind it.

Subscription keys

A subscription in APIM is a named container for a primary and secondary key, not an Azure subscription. Scopes are product, all APIs, a single API, the built-in all-access subscription, and standalone subscriptions that have no developer owner. By default the gateway reads the key from the Ocp-Apim-Subscription-Key header, then from the subscription-key query parameter if the header is absent. Both names can be changed per API.

• Query strings leak: keys sent as query parameters end up in proxy, browser and backend logs. Require the header and strip the query form.
• Keys reach the backend: by default the key is forwarded to the backend and can appear in backend logs. Microsoft documents removing it with set-header or set-query-parameter at the end of the inbound section.
• Open products are anonymous: if an API sits in an open product and a request carries an invalid key, the key is ignored and the call is treated as anonymous. "Subscription required" is on by default for new APIs and products; disabling it should always be paired with another control such as OAuth 2.0, client certificates or IP restrictions.
• Unpublishing is not revoking: unpublishing a product hides it from the portal but leaves its keys valid. Suspend or cancel the subscriptions.
• No group binding: subscriptions cannot be assigned to Entra security groups. Group based access needs policies that check token claims.

Token validation policies

validate-jwt checks signature, expiry, audience, issuer and required claims in the inbound section. Its defaults are sound: require-expiration-time and require-signed-tokens are true, clock-skew is 0 seconds and failures return 401. The risk lies in what you leave out. Always set audiences (Microsoft states at least one must be specified), set issuers, and use required-claims for scopes or roles rather than relying on a valid signature alone. Use openid-config so signing keys roll over automatically; the configuration is cached for one hour. Supported asymmetric algorithms are PS256, RS256, RS512 and ES256. For tokens issued by Microsoft Entra, Microsoft recommends the validate-azure-ad-token policy instead. See the JWT Security Guide for claim validation principles.

Admin roles and privileged access

APIM ships three built-in service roles and a set of workspace roles. Map them to job functions and avoid granting Service Contributor to developers who only need to edit one API.

• Custom roles: Microsoft documents cloning a built-in role and adding actions such as Microsoft.ApiManagement/service/apis/write scoped to one API. A custom role needs Microsoft.ApiManagement/service/read to see the instance in the portal.
• Credential read paths: backends, named values and authorisation providers return secrets only through a listSecrets action. Withhold Microsoft.ApiManagement/service/<entityType>/listSecrets/action from readers, and remember Microsoft's warning that write access returns credentials in PUT and PATCH responses.
• Certificate reuse: when a policy references a certificate by certificate-id, linked access is not checked, so a policy author can use any certificate in the instance.
• Privileged access discipline: make Contributor assignments eligible through Entra Privileged Identity Management rather than permanent, and review them with the Azure RBAC and Service Principals Guide.

Integrations, API tokens and service accounts

Managed identity to backends

The authentication-managed-identity policy obtains a Microsoft Entra token for the instance's system-assigned identity, or a user-assigned identity selected with client-id, for a given resource, and sends it to the backend in the Authorization header. Microsoft is explicit that APIM does not validate the destination, so tokens go wherever the policy sends them. Two controls follow: grant the identity only the Azure roles its backends need, and restrict policy editing, because anyone who can edit policies can obtain and forward the token. See the Azure Managed Identities Security Guide.

Microsoft notes that from March 2026 trusted service connectivity from the gateway through the "Allow Trusted Microsoft Services" firewall setting is no longer supported for data-plane traffic, so backend calls need another supported network path. Key Vault access needs Get and List secret permissions or the Key Vault Secrets User role.

Named values and stored secrets

• Key Vault references over plain secrets: keep backend passwords, API keys and signing keys in Key Vault and reference them as named values, so rotation happens in one place. See the Azure Key Vault Security Guide.
• Certificate versions: if the certificate version is omitted, APIM picks up a new Key Vault version within four hours.
• Subscription keys as non-human credentials: standalone subscriptions are effectively shared API keys. Record an owner, a consuming system and a rotation date for each, and set values through the Subscription Create Or Update API (properties.primaryKey, properties.secondaryKey) from your own rotation job, since APIM has no built-in expiry. See the API Key Management Guide.

Self-hosted gateway

The self-hosted gateway (Developer and Premium tiers) is a Linux container from mcr.microsoft.com that connects outbound on TCP 443 to its single APIM instance, sends a heartbeat every minute and polls for configuration every 10 seconds. Its default credential is a gateway access token that expires at least every 30 days and is backed by a rotatable gateway key; regenerating the key invalidates every token issued from it, and system events fire as a token nears expiry. Microsoft also documents an Entra app with a client secret or certificate, and recommends Entra workload identity on AKS because it uses federated credentials with short-lived tokens. Further points:

• Pin images: use a full version tag such as 2.0.0 in production, not v2, latest or beta.
• Treat the token as a Kubernetes secret: store it in a secret with restricted RBAC, never in a manifest in source control.
• TLS: TLS 1.2 is the default; from v2.1.1 cipher suites can be restricted with net.server.tls.ciphers.allowed-suites and net.client.tls.ciphers.allowed-suites.
• Configuration backup: a persistent volume lets stopped gateways start during an outage; protect that volume because it holds gateway configuration.

Developer portal

By default anyone can browse the portal and its APIs anonymously, although the test console is restricted. If your API catalogue is not meant to be public, enable "Redirect anonymous users to sign-in page" under Developer portal, Identities, Settings. Use Microsoft Entra ID for internal developers and Microsoft Entra External ID for external developers in new deployments; Microsoft describes basic username and password sign-in as less secure and Azure AD B2C as legacy (no longer sold to new customers since 1 May 2025). Delegation lets you route sign-up and subscription requests through your own approval system.

Logging and detection

Send diagnostic settings for the gateway, WebSocket connections and developer portal usage to a Log Analytics workspace using the resource-specific table ApiManagementGatewayLogs, and route the Azure activity log as well. Request and response bodies are off by default and are enabled per API under Settings, Diagnostic Logs; leave them off where payloads may contain credentials or personal data.

Microsoft Defender for APIs adds an inventory of APIM APIs, flags endpoints unused for 30 days, unauthenticated endpoints (none of subscription keys, JWT, client certificate or Entra token checks ran) and endpoints receiving external traffic, classifies sensitive data in bodies, and raises runtime alerts aligned to the OWASP API Security Top 10 that can be exported to Microsoft Sentinel.

Metrics that show the controls work:

• Percentage of APIs enforcing a token validation policy as well as, or instead of, a subscription key.
• Number of active subscriptions with no recorded owner or with keys older than your rotation period.
• Count of principals holding Service Contributor or policy write rights, trended monthly.
• Unauthenticated or inactive endpoints reported by Defender for APIs.
• Self-hosted gateways running unpinned image tags or tokens within seven days of expiry.

Hardening baseline

1. Inventory first: list APIs, products, subscriptions (including the all-access one), named values, backends and gateways. Use Defender for APIs where licensed.
2. Lock the management plane: reduce Service Contributor to a few PIM-eligible administrators, give developers workspace roles or custom roles scoped to their APIs, and deliver policy through reviewed infrastructure as code.
3. Enforce authentication on every API: keep "subscription required" on, add validate-azure-ad-token or validate-jwt with audiences, issuers and required claims, and test in a non-production instance before applying at product or global scope.
4. Strip credentials before the backend: remove subscription keys from forwarded requests and move backend secrets into Key Vault named values or replace them with managed identity.
5. Restrict the network: add an inbound private endpoint (Developer, Basic, Standard, Standard v2, Premium, Premium v2) then set publicNetworkAccess to Disabled; requests from outside the private path then receive 403. Private Link covers the gateway endpoint only and is not supported on self-hosted or workspace gateways.
6. Close the portal: require sign-in, move developers to Entra ID or Entra External ID, and route subscription approval through delegation or manual approval.
7. Harden self-hosted gateways: pin versions, use workload identity on AKS, rotate gateway keys, restrict cipher suites.
8. Turn on logging and review: diagnostic settings to Log Analytics, alerts on policy writes and listSecrets, and a quarterly subscription key review.

Rollback: apply new validation policies at API scope first, keep the previous policy in source control, and roll back by redeploying it. When rotating keys, move clients to the secondary key, regenerate the primary, then swap, so there is always one valid key.

Small versus large estates: a single team with one instance can rely on built-in roles and product subscriptions. Shared enterprise instances benefit from workspaces, custom roles per API and a separate instance or workspace gateway for regulated APIs.

Common misconfigurations

• Keys as the only control: subscription keys are long-lived shared secrets with no expiry. Leaked in a mobile app or front end bundle, they give anyone the same access as the client.
• validate-jwt without audiences or claims: a token signed by the right tenant for a different application passes signature checks. Always restrict audience and issuer.
• Broad policy editors: granting Service Contributor to many developers lets each of them obtain the managed identity token and see written backend credentials.
• All-access subscription left active: it bypasses product scope policies such as rate limits, and Microsoft says it should never be used for routine access or embedded in client apps.
• Bodies logged by default: enabling payload logging globally can store passwords, tokens and personal data in Log Analytics. See the JWT and Session Tokens in Code and Logs Guide.
• Unpinned self-hosted gateway images and tokens in manifests: rolling tags change underneath you, and gateway tokens committed to Git give a configuration channel to the instance.

Framework mapping

Practitioner checklist

• Suspend the built-in all-access subscription and any subscription without a named owner.
• Require the subscription key header, disable the query parameter form, and strip keys before forwarding to backends.
• Apply validate-azure-ad-token or validate-jwt with audiences, issuers and required claims on every externally reachable API.
• Limit API Management Service Contributor and policy write actions to PIM-eligible administrators; use workspace or custom roles for developers.
• Withhold listSecrets from readers and keep credential-bearing entities out of reach of broad write roles.
• Scope the instance managed identity to the minimum Azure roles its backends need, and review those assignments quarterly.
• Store backend secrets in Key Vault named values and rotate subscription keys with an automated primary and secondary swap.
• Enable a private endpoint and disable public network access where callers are internal.
• Require sign-in on the developer portal and move developers off basic username and password.
• Pin self-hosted gateway image versions, use workload identity on AKS and alert on token expiry events.

Standards and references

• Microsoft Learn: Subscriptions in Azure API Management
• Microsoft Learn: Azure API Management policy reference, validate-jwt
• Microsoft Learn: Use managed identities in Azure API Management
• Microsoft Learn: How to use role-based access control in Azure API Management
• Microsoft Learn: Self-hosted gateway authentication options
• Microsoft Learn: Connect privately to API Management using an inbound private endpoint
• Microsoft Learn: Monitor Azure API Management
• OWASP: API Security Top 10 2023

Related NHI Mgmt Group resources: API Security Guide · API Gateway Security Guide · Azure Managed Identities Security Guide · API Keys vs OAuth Tokens Guide