Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Security and hardening

An ASP.NET Core API answers 401 with Bearer error="invalid_token"

ErrorWWW-Authenticate: Bearer error="invalid_token"

Short answer

invalid_token in the WWW-Authenticate header means the access token is expired, revoked, malformed or invalid for another reason. In ASP.NET Core the usual reasons are expiry, a wrong audience or issuer, or a signature the API cannot verify. Read the error_description and the OnAuthenticationFailed exception.

  • Applies to ASP.NET Core 8, 9 and 10, Microsoft.AspNetCore.Authentication.JwtBearer
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the response headers. The error_description after invalid_token names the check that failed.

    curl -i -H "Authorization: Bearer $TOKEN" https://localhost:5001/api/values
  2. 2Match what you see, then jump to its fix

    1. 1The exception from OnAuthenticationFailed or the error_description points to expiryThe token has expiredFix
    2. 2The exception from OnAuthenticationFailed names the audience or the issuerThe audience or issuer in the token is not what the API expectsFix
    3. 3The exception from OnAuthenticationFailed mentions the signature or the signing keyThe signature cannot be verified with the keys the API holdsFix

What does the error look like?

  • WWW-Authenticate: Bearer error="invalid_token"
  • 401 Unauthorized

Cause 1 of 3

The token has expired

1Check

The API must validate the expiration of the token. Decode the payload and compare exp with the current time.

echo "$TOKEN" | cut -d. -f2 | tr '_-' '/+' | base64 -d 2>/dev/null; date +%s

2Fix

Request a new token from the issuer, or refresh it with a refresh token, and send that one.

curl -i -H "Authorization: Bearer $NEW_TOKEN" https://localhost:5001/api/values

3Verify

The status changes from 401 to 200.

curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $NEW_TOKEN" https://localhost:5001/api/values

Confirmed by learn.microsoft.com

Did this fix it?

Cause 2 of 3

The audience or issuer in the token is not what the API expects

1Check

A JWT bearer API should check the aud and iss claims against expected values. A token issued for another resource or another tenant fails that check.

echo "$TOKEN" | cut -d. -f2 | tr '_-' '/+' | base64 -d 2>/dev/null

2Fix

Request a token for this API, or set Audience and Authority (or ValidAudiences and ValidIssuers) to the values the token really carries.

builder.Services.AddAuthentication("Bearer").AddJwtBearer(o =>
{
    o.Authority = "https://login.example.com/<tenant>/v2.0";
    o.Audience = "api://my-api";
});

3Verify

A fresh token for this audience is accepted.

curl -i -H "Authorization: Bearer $NEW_TOKEN" https://localhost:5001/api/values

Confirmed by learn.microsoft.com

Did this fix it?

Cause 3 of 3

The signature cannot be verified with the keys the API holds

1Check

The signature proves the token was made by the issuer and not changed. Signing keys roll over, so an API with a fixed key or stale cached keys rejects new tokens. Libraries that read the issuer's metadata refresh keys for you.

curl -s https://login.example.com/<tenant>/v2.0/.well-known/openid-configuration

2Fix

Point the API at the issuer with Authority so JwtBearer loads the keys from the metadata, instead of pinning one key in code.

builder.Services.AddAuthentication("Bearer").AddJwtBearer(o =>
{
    o.Authority = "https://login.example.com/<tenant>/v2.0";
});

3Verify

A newly issued token validates after a restart.

curl -i -H "Authorization: Bearer $NEW_TOKEN" https://localhost:5001/api/values

Confirmed by learn.microsoft.com

Did this fix it?

How do I stop it coming back?

  • Refresh tokens before they expire instead of retrying with the old one.
  • Set Authority, not a hand-copied signing key, so key rollover needs no deploy.
  • Log the exception from OnAuthenticationFailed while debugging.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.