OAuth JWKS Resolution#

The @better-auth/oauth-provider package verifies JWT tokens at its logout, introspect, and revoke endpoints by resolving a JSON Web Key Set (JWKS) and using it to validate token signatures. All three endpoints rely on primitives exported from packages/core/src/oauth2/verify.ts: getJwks (used by logout) and verifyJwsAccessToken (used by introspect and revoke via getJwks internally).

JWKS Source Selection#

Each endpoint first calls getJwtPlugin(ctx.context) to locate the JWT plugin registered on the Better Auth context. The plugin's jwks.remoteUrl option then determines the fetch strategy:

• Introspect — validateJwtAccessToken builds jwksFetch as either the URL string or an async closure calling the JWT plugin endpoint, then passes it (with jwksCacheKey: jwtPlugin) to getJwks.
• Revoke — revokeJwtAccessToken uses identical logic: URL string or in-process closure, with jwksCacheKey: jwtPlugin 1.
• Logout — verifyLogoutHint selects remoteUrl if configured, otherwise constructs a URL as ${baseURL}${jwksPath ?? "/jwks"} and always makes an HTTP request via getJwks — it never calls jwtPlugin.endpoints.getJwks(ctx) directly and never passes jwksCacheKey 2.

Inconsistency: Logout always fetches over HTTP, even when the service is running in-process. Introspect and revoke avoid the HTTP round-trip by calling the JWT plugin endpoint directly when no remoteUrl is configured.

Caching Mechanics#

Caching is implemented in getJwksForVerification (the internal implementation behind getJwks).

Two cache structures#

For function sources without a jwksCacheKey, the key set is fetched on every call — no caching occurs 3. Introspect and revoke pass the JWT plugin instance as jwksCacheKey; because the plugin object is stable across requests, the WeakMap entry is reused. Logout uses a URL string, so it benefits only from the Map-based URL cache — not the WeakMap-based plugin-instance optimization.

TTL and cache-miss behavior#

• 5-minute TTL — JWKS_CACHE_TTL_MS: a cached entry is served until it ages past 5 minutes.
• kid-miss invalidation — getFreshJwksWithKid: if the JWT header carries a kid that is absent from the cached key set, the cache is bypassed and a fresh fetch is triggered.
• No-kid refetch cooldown — shouldRefetchCachedJwksWithoutKid: when a token has no kid and signature verification fails against a cached JWKS, one immediate retry is allowed; subsequent retries are rate-limited to once every 30 seconds (JWKS_NO_KID_REFETCH_COOLDOWN_MS) to prevent invalid tokens from hammering the JWKS endpoint.

JWT vs. Opaque Token Dispatch#

Introspect and revoke do not know upfront whether a token is a JWT or opaque. The JWKS verification is attempted first; if it fails with a shape error (e.g., JWSInvalid, TypeError), the endpoint falls back to an opaque DB lookup. JWT-specific errors (JWTExpired, JWTInvalid) resolve to { active: false } per RFC 7009/7662 rather than propagating 4.

Guard against plain session JWTs#

Because session JWTs and OAuth access tokens share the same issuer, algorithm, and signing key, validateJwtAccessToken requires the azp (authorized party) claim before reporting a token active 5. Only tokens issued through the OAuth token endpoint carry azp; plain session JWTs do not and are rejected. Revoke applies the same guard — tokens without azp resolve as a silent no-op 6.

verifyAccessTokenRequest (Resource Server Entry Point)#

For resource servers that need to validate tokens they receive, verifyAccessTokenRequest is the recommended entry point. It wraps verifyAccessTokenPayload, which:

1. Attempts local JWS verification via verifyJwsAccessToken when jwksUrl is provided and remoteVerify.force is not set.
2. Falls back to (or forces) remote introspection via remoteVerify.introspectUrl when configured.
3. Validates audience, issuer, and optional requiredScopes against the payload.

verifyBearerToken is a simpler variant that rejects DPoP-bound tokens outright; use verifyAccessTokenRequest when you need to handle both bearer and DPoP-bound tokens.

Key Fix: PR #9987#

PR #9987 (merged 2026-06-11) introduced the current caching model. Before the fix, function-based JWKS sources (in-process calls) had no stable cache key, causing the key set to be re-fetched on every token verification request, and no-kid verification failures could trigger unbounded JWKS refetches. After the fix, jwksCacheKey (the plugin instance) scopes the WeakMap cache and the 30-second cooldown rate-limits no-kid retries.

Key Files#