JWKS

A JSON Web Key Set (RFC 7517) is a JSON document containing the public keys that ThunderID uses to sign JWTs, including ID tokens, access tokens, and other signed responses. Resource servers and clients fetch the document, find the key whose kid matches the JWT's kid header, and verify the signature locally.

How It Works

curl https://thunderid.example.com/oauth2/jwks

{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "thunder-2026-01",
      "alg": "RS256",
      "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWh...",
      "e": "AQAB"
    },
    {
      "kty": "EC",
      "use": "sig",
      "kid": "thunder-ec-2026-01",
      "alg": "ES256",
      "crv": "P-256",
      "x": "WKn-ZIDIDvZRT5ZAakBPsCYR0V6cZF9NyfTQk6c2eXg",
      "y": "y77t-RvAHRKTsSGdIYUfweuOvwrvDD-Q3Hi5rew0haE"
    }
  ]
}

The endpoint is public and idempotent: cache the response in line with your tolerance for key rotation.

How ThunderID Implements It

Aspect	Behavior
Endpoint	GET /oauth2/jwks
Discovery field	jwks_uri in Server Metadata
Supported key types	RSA, EC (P-256, P-384, P-521), OKP (Ed25519 / EdDSA)
Signing algorithms covered	RS256, RS512, PS256, ES256, ES384, ES512, EdDSA
Private keys	Never returned: the document contains only public material
Key rotation	New keys appear in the document before they're used for signing; old keys remain published while there are still valid tokens signed by them

Try It in ThunderID

The JWKS endpoint is always available. Nothing needs to be configured at the application level.

Consume JWKS from a Resource Server

Most JWT libraries accept a jwks_uri and handle caching, key lookup by kid, and rotation automatically:

import { createRemoteJWKSet, jwtVerify } from 'jose';

const JWKS = createRemoteJWKSet(
  new URL('https://thunderid.example.com/oauth2/jwks')
);

const { payload } = await jwtVerify(token, JWKS, {
  issuer: 'https://thunderid.example.com',
  audience: 'https://api.example.com/payments',
});

Caching Guidance

• Cache the JWKS response for minutes, not hours, long enough to avoid pressure on the endpoint, short enough to absorb a key rotation.
• On signature failure with an unknown kid, refresh the cache once and retry. Do not loop.
• Do not embed JWKS into your application. Fetch it at runtime so key rotation does not require a redeploy.

Related Guides

• Server Metadata, advertises jwks_uri
• Token Introspection, the alternative to local JWT validation
• Token Formats, signed and encrypted ID token / UserInfo formats
• Client Authentication Methods, private_key_jwt clients publish their own JWKS, separate from this endpoint