What the aud claim is for
The aud (audience) claim names the services a token is meant for. It’s a string, or an array of strings.
RFC 7519 says a service that receives a token
must find itself in aud and reject the token if it
doesn’t. That stops a token issued for one API being replayed against another API that trusts the same sign-in
provider.
So “audience invalid” means the token is genuine but was issued for someone else. To see who, paste it into the
JWT Security Inspector and compare its aud with the audience
your API is configured to expect. It runs in your browser, so the token isn’t sent anywhere.
How each library reports it
- Node.js, jsonwebtoken
JsonWebTokenError: jwt audience invalid. expected: https://api.example.com- Node.js, jose
JWTClaimValidationFailed: unexpected "aud" claim value- Python, PyJWT
-
InvalidAudienceError: Audience doesn't match, orInvalid audiencewhen the token has anaudand you didn’t pass one to check - .NET
IDX10214: Audience validation failed.- Spring Security
The aud claim is not valid- Go, golang-jwt
token has invalid claims: token has invalid audience
PyJWT’s second message catches people out: it rejects any token that carries an audience unless you tell it which audience to expect, even if you never meant to check one.
Cause 1: an ID token is sent to the API
OpenID Connect sign-in returns two tokens. The
ID token tells your app who signed in, so its
aud is your app’s client ID. The access token is for calling your API, so its
aud is the API. Both are often JWTs and easy to mix up. Send the access token in the
Authorization header, and keep the ID token in the app.
Cause 2: the token was requested for a different audience
Each provider decides the audience from how the token was requested:
- Auth0
-
Pass
audience, the API’s identifier, when you request the token. Without it, and without a default audience in the tenant settings, you get an opaque access token that isn’t a JWT at all. - Okta
-
The audience is set on the
authorization server. The default custom
server uses
api://default, so configure your API to expect that, or the audience you set. - Microsoft Entra ID
-
v2.0 access tokens carry
the API’s client ID (a GUID) as
aud. v1.0 tokens carry the resource the client asked for, often the App ID URI such asapi://…. The API’saccessTokenAcceptedVersionsetting decides which you get, so accept the one it issues. - Amazon Cognito
-
ID tokens carry the app client ID in
aud, but access tokens have noaudat all: they carryclient_id. Checkclient_idfor access tokens, as aws-jwt-verify does. - Firebase Auth
-
ID tokens carry your Firebase project ID as
aud. Verify them with the Admin SDK’sverifyIdToken(), which checks the audience and issuer for you. - Google sign-in
- ID tokens carry your OAuth client ID as
aud.
Cause 3: the strings differ slightly
Audiences are compared as exact strings. https://api.example.com,
https://api.example.com/ and http://api.example.com are three different audiences. Copy
the value from a real token into your API’s configuration rather than typing it.
Cause 4: your own code compares aud wrongly
Hand-written checks often assume aud is a string. Auth0, for one, issues an array when a token is
requested for an API with the openid scope: your API plus its own userinfo endpoint. A check like
payload.aud === expected then fails. Let the library check the audience, or handle both shapes:
// aud can be a string or an array of strings.
const audiences = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
if (!audiences.includes('https://api.example.com')) {
throw new Error('Token is for a different audience');
}
Cause 5: environments are mixed up
A token from staging sent to production, or an API whose configuration names the other environment’s audience, fails the same way. Give each environment its own audience, and check which one the failing request came from.
Setting the audience correctly
Check the audience and the issuer together, and pin the algorithm while you’re there.
Node.js, jsonwebtoken
import jwt from 'jsonwebtoken';
const claims = jwt.verify(token, publicKey, {
algorithms: ['RS256'],
issuer: 'https://auth.example.com/',
audience: 'https://api.example.com',
});
Node.js, jose
import { createRemoteJWKSet, jwtVerify } from 'jose';
const JWKS = createRemoteJWKSet(new URL('https://auth.example.com/.well-known/jwks.json'));
const { payload } = await jwtVerify(token, JWKS, {
issuer: 'https://auth.example.com/',
audience: 'https://api.example.com',
});
Python, PyJWT
import jwt
claims = jwt.decode(
token,
public_key,
algorithms=["RS256"],
issuer="https://auth.example.com/",
audience="https://api.example.com",
)
Don’t switch the check off
jsonwebtoken skips the audience check when you don’t pass audience. PyJWT does when you pass
options={"verify_aud": False}, and .NET when you set ValidateAudience = false.
Each one makes your API accept any token from your sign-in provider, including tokens issued for other apps and other
APIs. Fix the audience instead.
If the error is about time rather than audience, read Fixing “jwt expired”. For what every other claim means, see JWT claims, explained.