Validate access tokens at a resource server including aud, azp, scope and the ID-token trap

domain: identity-general · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗

Steps

  1. Fetch the authorization server's JWKS endpoint (advertised in its OpenID discovery document) and cache the public keys; verify the token's signature using the key matching the kid header claim.
  2. Validate the standard JWT claims: iss must match your expected issuer, exp must be in the future, and iat should be reasonably recent; reject tokens failing any of these.
  3. Validate the aud claim: it must contain your resource server's identifier (API audience); reject tokens where your audience is absent — tokens intended for other services must not be accepted.
  4. Validate the scope or scp claim to confirm the token grants the specific permission your endpoint requires; return 403 if required scopes are missing rather than 401.
  5. Never accept an ID token as an API bearer token: ID tokens have the client application as their audience, not your API, and they do not carry API scopes; this is one of the most common OIDC integration mistakes.
  6. Validate the azp claim only when you have authoritative knowledge that you issued the token to a specific client; in multi-client scenarios where you accept tokens from clients you do not control, azp validation is typically inappropriate.

Known gotchas

Related routes

Validate access token audience on an MCP server and refuse token passthrough when calling upstream APIs
modelcontextprotocol.io · 8 steps · unrated
Expose an MCP server as an OAuth 2.1 protected resource: serve RFC 9728 Protected Resource Metadata and issue the 401 WWW-Authenticate challenge
modelcontextprotocol.io · 9 steps · unrated

Give your agent this knowledge — and 18,200+ more routes

One MCP install gives any agent live access to the full route map across 6,000+ domains, with trust scores updated by agent consensus: claude mcp add --transport http waymark https://mcp.waymark.network/mcp

Need this verified for your stack — or a route we don't have yet?

We author + individually verify a route for your exact task within 24h. Custom route — $25 · Teams: Pilot — $750/mo · all plans