JWKS in multi-tenant apps: key rotation and per-tenant keys

How to host a JWKS endpoint, when to rotate keys, and the question of per-tenant keys (almost always: don't).

Last updated: May 2026

shield

Private: Decoding, analysis, signature verification, and token generation all run in your browser. Nothing is sent to any server, except a JWKS URL you explicitly enter and click Verify on.

Paste your JWT

At a glance

Standard JWKS endpoint: /.well-known/jwks.json
Cache duration: 5–60 minutes (verifier-side)
Active key indicator: kid header in the JWT
Rotation frequency: 90 days (typical), or on incident

A JWKS (JSON Web Key Set) is a JSON document that lists the public keys a verifier should accept. JWKS makes key rotation painless: the issuer can add a new key, mark it the active signing key, and verifiers fetch the updated set on the next request — no coordinated rollout. For multi-tenant apps, the question that arises is whether to use one keyset across tenants or per-tenant keys; the answer is almost always one set.

How JWKS rotation works in practice

Day 1: you publish keys A and B in your JWKS, but only sign new tokens with A. Verifiers cache the JWKS for ≤60 minutes and accept tokens signed by either key.

Day N: switch the signing key to B. New tokens carry `kid: "B"`. Within one cache duration, every verifier has the new JWKS and accepts B. Tokens signed by A continue to verify until they expire naturally.

Day N + access-token-lifetime: every live token has rotated to B. You can remove A from the JWKS. Done — zero downtime, no coordinated cutover.

Frequently asked questions

Should I have one signing key per tenant?expand_more

Almost never. Per-tenant keys multiply key-management complexity by the number of tenants you have, and offer marginal isolation benefit because the issuer is the same in either case. Use one keyset, rotate keys regularly, and rely on the regular `tenant_id` claim for tenant scoping.

When is a per-tenant key actually right?expand_more

When a regulated tenant requires its own cryptographic isolation as a contractual term — usually government or healthcare. In those cases, a separate signing key per tenant (with separate JWKS endpoints) is part of the deal. Most products will never need this.

How do verifiers know which key to use?expand_more

The JWT header includes a `kid` (key id). The verifier fetches the JWKS, finds the key with the matching `kid`, and uses that public key to verify. During rotation you publish both the old and new key; once all live tokens have rotated, you remove the old key.

Short access tokens limit the blast radius of a leak. Long tokens are convenient. Here's how to pick a number, with reasoning.

JWT algorithm confusion: alg: none, HS256-vs-RS256, and how to defend

Algorithm confusion attacks exploit a verifier that trusts the header's alg field. Pin the algorithm at the verifier and reject anything else.