JWKS

A JWKS is a JSON document with a keys array, each entry a public key in JWK format with an identifier (kid), a key type and algorithm, and the key material. Identity providers publish one at a well-known URL so that every API receiving their tokens can verify signatures without sharing any secret.

How it works

A signed JWT names the key it was signed with in the kid field of its header. The verifier fetches the issuer's JWKS (usually found through the OpenID discovery document), picks the key with that kid, and checks the signature. Keys are rotated by publishing the new one alongside the old before switching, so verifiers should cache the set but refetch on an unknown kid.

The misconception

That the key set can be fetched once and baked into configuration. Providers rotate keys; a verifier with a hard-coded key starts rejecting every valid token on rotation day. The opposite mistake — fetching on every request — makes the identity provider a dependency of every call.

Try it here

GET /identity/v1/jwks returns the Modern Identity API's demo key set, and its discovery document at GET /identity/v1/.well-known/openid-configuration points to it, the way a real provider's does.

Sources

Other terms

JWT (JSON Web Token) — A compact format for claims, represented as a signed JWS or encrypted JWE.
OpenID Connect — An identity layer on top of OAuth 2.0 that tells the client who the user is, in a signed ID token.
Bearer token — A credential where possession alone grants access — whoever holds it can use it.
Refresh token — A long-lived credential used only to obtain new short-lived access tokens, without asking the user to log in again.
OAuth 2.0 — The standard framework for letting an application get a limited access token, instead of handling the user's password.
PKCE — Proof Key for Code Exchange — a one-time secret that stops a stolen OAuth authorization code from being redeemed by anyone else.

All glossary terms · Testing techniques · All 39 mock REST APIs

Last updated 16 October 2026