Validate JWTs: what the API backend must actually check

Decoding explains content; validation establishes trust

JWT is a format for structured claims. The commonly seen compact signed form consists of a header, payload and signature. The full JWT format supports other forms, including encrypted tokens. ‘JWT always has three parts’ is therefore not universally true. An ordinary signed payload is readable; Base64url is not encryption. RFC 7519, sections 3 and 5, describes the format.

Decoding helps with debugging, but the content initially comes from the sender. Do not copy real tokens into public decoders, tickets or chats. Use synthetic claims for illustrations and a controlled internal diagnostic path for an actual incident.

Define the accepted token contract in writing

For a fictional document API, the contract could look like this:

A standard can specify these rules. RFC 9068 is a particular profile for OAuth JWT access tokens, not the universal definition of all JWTs. Its contract includes a signature, typ set to at+jwt or application/at+jwt, and certain mandatory claims. An access token under a different agreement must not silently be described as conforming to this profile. See RFC 9068, sections 2 and 4.

Call the library with trusted requirements

Use a maintained library with a verification call. A call named decode, or manually parsing dots and JSON, does not fulfil this task. The specific API differs between libraries; what matters is the verifiable effect:

1. Bound format and size. Reject malformed or excessively large inputs before they trigger expensive processing.
2. Specify algorithm and key. The application permits only suitable methods. The unverified alg in the token does not independently select a new trust rule.
3. Check cryptographic validity. For signed access tokens, the signature must match a key trusted for the issuer. Failed checks result in rejection.
4. Check purpose, issuer and audience. Accept only the agreed token type, expected iss and aud intended for this API.
5. Check time and required claims. Actually enforce expiry, earliest validity where applicable, and profile-specific requirements; merely reading them is insufficient.
6. Decide business permissions. The application combines scope, identity, tenant, object and action.

The JWT Security BCP RFC 8725, section 3, requires algorithm verification, binding keys to the issuer and separating different token types, among other things. For the signed API access token described here, alg: none is not an acceptable shortcut. OIDC login rules must not replace resource validation.

Check expiry and time with bounded tolerance

exp specifies expiry: at and after that time, the token must no longer be accepted. nbf limits the earliest use; iat states the issuance time and is not an expiry date by itself. Values are NumericDate timestamps, not milliseconds from any arbitrary programming interface. RFC 7519, sections 4.1.4 to 4.1.6, defines their meaning.

A small explicit clock tolerance may be necessary. Determine it from synchronised systems and actual requirements. Using generous tolerance to fix a time error undesirably extends usability. Also check whether the library merely skips a missing claim: anything your contract requires must cause rejection when absent.

The base JWT specification does not require every registered claim for every application. Your profile can and must be stricter. ‘exp is optional in JWT’ therefore does not justify accepting an indefinitely valid token under a contract that requires expiry.

Handle key rotation and JWKS in a controlled way

A JWKS is a collection of published keys. With asymmetric signatures, the issuer publishes the public keys intended for verification; the private signing key remains protected. OIDC Discovery describes issuer and jwks_uri, among other fields. The metadata must match the expected issuer. See OpenID Connect Discovery, sections 3 and 4.3.

A kid helps select within the trusted key set. It does not authorise fetching an arbitrary server named by the token. Bound key fetching, network destinations and error handling. Unknown keys must not trigger unlimited fetch loops; a network error must not disable signature verification.

Plan normal key rotation with the issuer: publish new verification keys, issue new tokens and retain old keys only as long as the agreed transition requires. A compromised signing key, however, may require immediate withdrawal of trust. Caches and every verifying instance belong in the evidence. No universal cache duration can be derived from the token format.

Test targeted negative cases

Create the following variants only with your own test infrastructure and synthetic identities. The table is a test template, not a report of completed tests:

Add legitimate key rotation and failure of the key source. This shows whether availability and the security boundary work as planned together. Record the reason and time of rejection without logging entire tokens.

Signature verification does not automatically solve revocation

A locally validated token may remain cryptographically valid despite a blocked user session. If your product promises immediate withdrawal, suitable state checks, token introspection or another verified mechanism must enforce it. Short lifetimes limit the window but do not replace arbitrary promises of immediate blocking. RFC 7662 describes token introspection as one possible component.

Introduce stricter validation first with your own clients and documented token profiles. Rollback restores the previous secure configuration; it disables neither signature nor audience checks. The API Security Check does not validate access tokens. Use your integration tests for this, followed by authorisation checks. Sources checked: 27 September 2026.

Next steps