Azure API Management managed identity problems are annoying because the failure usually shows up as a plain 401, 403 or “the backend said no.” Underneath, API Management (APIM) may be juggling policy order, Microsoft Entra token audiences, backend permissions, Key Vault named values, gateway tracing and networking.
This guide covers how the flow works, which identity type to choose, the three common patterns (Key Vault named values, backend authentication and mTLS certificates), where each breaks, and the guardrails that keep your gateway from becoming a token vending machine.
Admin quick take
Most APIM managed identity failures are permission, audience or policy-scope problems.
- 401 from the backend: check the token audience and whether the backend validates the issuer and app correctly.
- 403 from the backend or Key Vault: check role assignments, access policies, firewall and private endpoint paths, and which identity APIM actually used.
- Named value not updating: Key Vault-backed named values refresh automatically, but Microsoft documents a window of up to four hours; manual refresh is available.
How Azure API Management managed identity works
Instead of embedding credentials in APIM, Azure creates an identity in Microsoft Entra ID. APIM uses it to reach resources such as Key Vault, or to request a token for an Entra-protected backend, and Azure manages the credential material. A few facts matter most for troubleshooting:
- A system-assigned identity is created with the APIM instance and removed when it’s deleted.
- User-assigned identities are standalone Azure resources attached to the instance.
- In the
authentication-managed-identitypolicy, ifclient-idis omitted, the system-assigned identity is assumed. - APIM caches the managed identity token until it expires.
The last two are where many bugs hide. If a policy was meant to use a user-assigned identity but the client-id is missing or wrong, APIM requests a token as the system-assigned identity and the backend rejects it.
System-assigned vs. user-assigned identity
| Option | Best for | Watch out for |
|---|---|---|
| System-assigned | One APIM instance with simple Key Vault or backend access. | Tied to the APIM lifecycle; delete the instance and the identity goes with it. |
| User-assigned | Shared access patterns, stable lifecycle, reusable backend trust, blue/green APIM migrations. | You manage the identity resource and must pass the right client ID in policies. |
A sensible default: start with system-assigned for a single instance, and move to user-assigned when you need a stable lifecycle, reuse across services or cleaner separation between gateway deployment and backend authorization.
Step 1: Confirm which identity APIM is using
In the APIM instance, open Managed identities. Confirm whether the system-assigned identity is enabled, which user-assigned identities are attached, and which one each policy is meant to use.
<authentication-managed-identity
resource="https://vault.azure.net"
output-token-variable-name="msi-access-token"
ignore-error="false" />No client-id here, so APIM uses the system-assigned identity. For a user-assigned identity, pass the client ID deliberately and document why that identity exists:
<authentication-managed-identity
resource="api://your-backend-app-id"
client-id="00000000-0000-0000-0000-000000000000" />Guardrail: treat APIM policy editing rights as privileged access. Microsoft warns that users who can modify policies may be able to use the managed identity to obtain or route tokens if the identity has broad permissions.
Step 2: Match the token audience to the backend
The policy’s resource value tells Microsoft Entra ID which audience the token is for. A Key Vault token isn’t a token for your custom API, and neither is a token for Azure Storage.
| Backend target | Common resource/audience | What to verify |
|---|---|---|
| Azure Key Vault | https://vault.azure.net | APIM identity has secret permissions or an RBAC role, and the network path is allowed. |
| Custom Entra-protected API | api://<application-id-uri> | Backend validates the same audience and trusts the issuing tenant. |
| Azure service backend | Service-specific resource URI | Use the documented audience, not a guessed URL. |
A 401 from the backend points at token validation, so check that before changing permissions. A 403 usually means the token is valid but under-authorized.
Step 3: Troubleshoot Key Vault named values separately
Named values can hold plain values, encrypted secrets or references to Key Vault secrets, and Microsoft recommends Key Vault references for reuse and granular access control. Keep two scenarios apart:
- APIM fetching a Key Vault secret for a named value: the APIM identity needs access to that secret and a working network path.
- APIM calling a backend with a managed identity token: the backend must trust and authorize the APIM identity.
Setup checklist for a Key Vault-backed named value:
- Enable a managed identity on the APIM instance.
- Store the secret in Key Vault.
- Grant APIM data-plane read access to the secrets it needs, not broad Owner or Contributor roles.
- Create a named value that references the secret identifier, and use it in policy.
- Document the owner and rotation expectations.
After a secret rotates, APIM picks up the new value within the documented refresh window (up to four hours). If you test thirty seconds after rotating, use the manual refresh in the portal or management REST API before declaring an outage.
Step 4: Check certificates for backend mTLS
For mutual TLS to a backend, APIM can reference client certificates stored in Key Vault instead of uploaded files, so they can be reused, permissioned and rotated centrally. Certificates updated in Key Vault rotate into APIM within the same refresh window, with manual refresh available. Failures usually trace back to the same causes as named values: identity permissions, the secret identifier, or the network path to Key Vault.
Step 5: Use tracing carefully
Request tracing shows processing steps and policy behavior. Microsoft now recommends enabling tracing per API with a time-limited token; the older Ocp-Apim-Trace header behavior is no longer supported. Trace output can expose sensitive data, so handle it like production evidence.
The trace policy adds custom data to tracing output, Application Insights and resource logs. Record safe breadcrumbs such as branch decisions and correlation IDs, never tokens, secrets, Authorization headers or customer payloads:
<trace source="apim-auth" severity="information">
<message>Managed identity branch selected for backend call.</message>
</trace>Read the status code as a clue
| Symptom | Likely area | First checks |
|---|---|---|
| Policy fails before the backend call | Policy syntax or token acquisition | Policy scope, XML order, identity enabled, resource value. |
| Backend returns 401 | Token validation | Audience, issuer, app registration, backend auth middleware, clock skew. |
| Backend returns 403 | Authorization | Role assignment, app role, ACL, Key Vault RBAC or access policy, user-assigned vs. system identity. |
| Key Vault named value fails | Secret access or network | Secret permissions, firewall or private endpoint route, secret identifier and version. |
| Works in one environment only | Identity lifecycle mismatch | Compare object and client IDs and role assignments across environments. |
| Works after a while | Cache or propagation | Token cache, named value refresh, role assignment propagation. |
Azure API Management managed identity runbook
- Identify the failing hop: policy evaluation, token acquisition, named value resolution, or the backend after it receives the call.
- Confirm the policy scope. Global, product, API and operation policies combine, so the fault may be inherited.
- Confirm identity selection: no
client-idmeans system-assigned. - Verify the token audience against what the backend expects.
- Verify authorization: Azure RBAC, Key Vault permissions, app roles, backend ACLs and tenant assumptions.
- Check network controls: firewall rules, private endpoints, DNS and whether APIM has a reachable path.
- Enable safe, time-limited tracing.
- Review diagnostics: APIM resource logs and Application Insights, so the next incident has breadcrumbs.
Guardrails for production APIM
Use user-assigned identities when ownership, reuse, lifecycle or permission boundaries matter.
Require change control for authentication policies and monitor policy changes as privileged operations.
Use Key Vault-backed named values and certificates, and document refresh steps.
Log decisions and correlation IDs, not tokens, secrets or request bodies.
Azure API Management managed identity removes stored credentials from policies, but it still needs least privilege, correct audiences, scoped policy access and diagnostics that are on before the incident. Pair this guide with Azure diagnostic settings policy, App Service Key Vault reference fixes and APIM Key Vault certificates.
Last reviewed: October 2026
Sources
- Use managed identities in Azure API Management (Microsoft Learn)
- authentication-managed-identity policy reference (Microsoft Learn)
- Use named values in API Management policies (Microsoft Learn)
- Secure backends with client certificate authentication (Microsoft Learn)
- Policies in Azure API Management (Microsoft Learn)
- Debug APIs using request tracing (Microsoft Learn)
- API Management trace policy (Microsoft Learn)
- Azure Key Vault RBAC guide (Microsoft Learn)
Discover more from Cloud Osprey
Subscribe to get the latest posts sent to your email.
