Unauthorized
Azure returns `Unauthorized` (401) when request authentication is missing, invalid, expired, or mismatched for the target endpoint.
Last reviewed: February 21, 2026|Source-backed guidance under our editorial policy
Start Here
Use the closest compare guide, playbook, or adjacent error page to narrow the decision faster before you start changing production systems.
This page is part of the Error Reference library. Learn more about the project or report a correction.
What Does Unauthorized Mean?
Identity verification failed before authorization checks, so the request cannot reach permission evaluation until authentication context is corrected.
Common Causes
- -Access token is expired, missing, or signed for a different audience than the target API.
- -Token was issued by the wrong tenant or authority for the subscription context.
- -Credential rotation updated secret/certificate in one environment but not all runtimes.
- -Intermediary layers strip or alter Authorization headers before request reaches Azure endpoint.
How to Fix Unauthorized
- 1Decode token claims (
iss,aud,tid,exp) and compare with target service requirements. - 2Acquire a fresh token from the correct tenant authority and retry the same request.
- 3Verify all running instances use the latest rotated secret/certificate material.
- 4Confirm Authorization header survives proxies, gateways, and service mesh hops unchanged.
Step-by-Step Diagnosis for Unauthorized
- 1Capture failing request metadata and response headers (including auth challenge details if present).
- 2Validate runtime clock sync and token expiration windows across deployment nodes.
- 3Check credential source precedence in SDK/CLI/environment settings to identify stale token paths.
- 4Replay request using a known-good auth flow to isolate client versus infrastructure mutation issues.
Token Claim and Authority Validation
- -Inspect claim alignment with endpoint expectations (example: token
audtargets graph endpoint while call goes to ARM management endpoint). - -Verify tenant authority used by identity client (example: service principal obtains token from wrong Entra tenant and receives 401).
Credential Lifecycle and Transport Integrity
- -Audit rollout completeness for rotated secrets/certs (example: one worker pool still serves expired certificate credentials).
- -Trace Authorization header through network intermediaries (example: ingress policy strips bearer token header on specific route).
Seen in Production
CI pipeline token cached from prior tenant context
Frequency: common
Example: Deployment calls ARM with stale token and receives Unauthorized.
Fix: Force tenant-scoped reauthentication and clear token cache per pipeline run.
Secret rotation completed in primary cluster but not disaster-recovery nodes
Frequency: rare
Example: Failover traffic receives 401 due to outdated credential material.
Fix: Coordinate phased secret rollout validation across all runtime pools.
Debugging Tools
- -JWT claim decoder (
iss,aud,tid,exp) - -az account get-access-token diagnostics
- -Identity SDK verbose logging
- -Gateway/proxy header trace capture
How to Verify the Fix
- -Replay the original request and confirm 401 responses disappear for the corrected auth path.
- -Validate token refresh and renewal behavior under sustained load and node restarts.
- -Confirm logs show stable successful authentication across all deployment environments.
How to Prevent Recurrence
- -Centralize token acquisition logic and enforce one authority configuration per environment.
- -Monitor token expiry, clock drift, and credential rollover events with proactive alerts.
- -Add auth preflight tests for issuer/audience/tenant before production deployment stages.
Pro Tip
- -emit redacted token claim fingerprints in diagnostics so you can detect cross-tenant token drift without exposing credential material.
Official References
Provider Context
This guidance is specific to Azure services. Always validate implementation details against official provider documentation before deploying to production.