How to Verify JWTs Safely: Claims, Signatures, Algorithms, and Common Mistakes

Overview

A JSON Web Token (JWT) is a compact representation of claims that can be passed between systems. A signed JWT commonly has three base64url-encoded parts separated by periods: a header, a payload, and a signature. The header describes the token type and signing algorithm; the payload contains claims; and the signature helps the receiving application detect unauthorized changes.

Decoding is not verification. Anyone who has a token can usually read its header and payload because base64url encoding is not encryption. A JWT decoder is useful for inspecting structure during development, but an application must verify the signature and validate the claims before using the token for authorization or identity decisions. Avoid pasting production tokens into online tools; use local, controlled tooling instead. The JWT decoder and validator guide covers safer inspection practices.

A practical validation process answers four questions:

• Was the token signed with an algorithm and key the application explicitly accepts?
• Does the signature match the complete header and payload?
• Was the token issued by the expected authority for this application?
• Is the token currently valid for this API, user, action, and environment?

These checks are part of API authentication and should be implemented by a maintained, reputable JWT library rather than handwritten cryptographic code. The exact configuration depends on whether the token uses a shared secret, such as an HMAC algorithm, or an asymmetric key pair, such as RSA or elliptic-curve signing.

Checklist by scenario

When receiving an access token at an API

1. Parse the structure safely. Confirm that the input has the expected compact format. Treat every decoded value as untrusted data. Parsing a token does not establish authenticity.
2. Use a configured algorithm allowlist. Select the permitted algorithm in server-side configuration, not from the token alone. Reject unexpected algorithms, including unsigned or otherwise unsupported options.
3. Choose trusted verification keys. Use the expected configured secret or a trusted key set. Do not automatically fetch a key from a URL supplied by an untrusted token header. If a key identifier such as kid is used, resolve it only within the trusted key set and handle unknown identifiers as failures.
4. Verify the signature. The signature must be checked against the exact encoded header and payload. A token with a valid-looking payload but an invalid signature must not be accepted.
5. Validate the issuer. Compare iss with the exact issuer identifier configured for this API. Similar-looking issuer values should not be treated as equivalent without an explicit rule.
6. Validate the audience. Confirm that aud identifies the current API or service. A token issued for one service should not automatically authorize access to another.
7. Check time claims. Enforce exp when the application requires expiration, and evaluate nbf when present. Use a narrowly defined clock-skew allowance only when operationally necessary. Do not turn a large tolerance into an informal extension of token lifetime.
8. Apply authorization rules. Claims such as scope, roles, or permissions should be interpreted according to the API's documented policy. Successful JWT verification proves token integrity; it does not prove that the requested operation is allowed.

When validating an identity token in a client login flow

Identity tokens and access tokens serve different purposes. An identity token may describe an authenticated user to a client, while an access token is intended for a resource server. Check that the token type matches the flow and that the intended audience is the client or service receiving it. Validate the issuer, audience, signature, expiration, and any flow-specific values required by the identity provider. Do not use an identity token as a general-purpose API access token merely because it is signed.

When keys rotate

Design key handling before rotation occurs. Maintain a trusted key set that can contain the current key and any still-valid previous key needed for a controlled transition. Cache key metadata for a bounded period, refresh it through an authenticated or otherwise trusted channel, and define behavior for an unknown kid. Avoid accepting arbitrary keys supplied in the JWT header. Test rotation in a non-production environment so that verification does not depend on a single hard-coded key.

When investigating a failed token

Record a safe diagnostic category rather than the full token. Useful categories include malformed structure, unsupported algorithm, unknown key identifier, invalid signature, wrong issuer, wrong audience, expired token, and not-yet-valid token. Return a generic authentication failure to the caller while keeping detailed, access-controlled logs for investigation.

What to double-check

Algorithm and key separation

Algorithm confusion can occur when an application accepts an algorithm chosen by the token or uses a key in a way the verifier did not intend. Keep the algorithm, key type, and verification operation bound together in configuration. For example, do not treat a public key as an HMAC secret, and do not silently switch between symmetric and asymmetric verification based on attacker-controlled input. Reject an algorithm mismatch rather than attempting a fallback.

Claims are data, not instructions

Claims such as sub, email, and name can help identify a subject after successful verification, but they should not be trusted before that point. Validate expected types and formats as well. A claim expected to be a string should not be accepted as an array simply because a generic parser permits it. Treat optional claims as optional and define what happens when a required claim is absent.

Privacy and logging

JWT payloads may contain personal data, internal identifiers, scopes, or other information that should not appear in logs, browser history, URLs, error messages, or support tickets. Prefer short-lived, purpose-specific tokens with minimal claims. If confidentiality is required, a signed JWT is not enough; signing protects integrity, not secrecy. Consider whether an opaque reference token would reduce data exposure and simplify revocation.

Transport and storage

Signature verification does not replace transport security. Send tokens only over protected connections, use secure storage appropriate to the application architecture, and avoid placing bearer tokens in locations where unrelated scripts or third parties can read them. A stolen but valid bearer token may be usable until it expires or is revoked, so token lifetime, scope, and exposure controls all matter.

Common mistakes

• Only decoding the payload: Base64url decoding reveals content but provides no proof that the issuer created it.
• Trusting the header's algorithm: The header is untrusted until the signature and policy checks succeed.
• Checking only expiration: A token can be unexpired but intended for another issuer, audience, environment, or permission set.
• Accepting any key returned by a URL: Key discovery should be constrained to trusted configuration and protected against unexpected network requests.
• Using broad exception handling: Treating every verification error as a successful fallback can turn configuration failures into authentication bypasses.
• Logging full bearer tokens: Logs are frequently copied, retained, and accessed by more people and systems than expected.
• Confusing authentication with authorization: A verified subject still needs permission for the requested resource and action.
• Writing custom cryptography: Prefer a well-maintained library and test its documented validation behavior rather than implementing signature checks yourself.

When to revisit

Review JWT verification whenever the underlying inputs or workflow changes. Revisit it before a new API, identity provider, environment, or client is introduced; when signing algorithms, key storage, scopes, or token lifetimes change; and before a planned key rotation. It also deserves attention after an authentication incident, a dependency upgrade, a change to logging or monitoring, or the addition of a new service that consumes tokens.

Use this short release checklist:

1. Confirm the accepted algorithms and key sources are explicit and environment-specific.
2. Test valid, malformed, tampered, expired, not-yet-valid, wrong-issuer, and wrong-audience tokens.
3. Test unknown and rotated kid values without accepting untrusted keys.
4. Verify that authorization checks remain separate from signature validation.
5. Search logs, traces, analytics, and error reports for accidental token exposure.
6. Document the expected failure behavior and provide a safe operational path for key updates.

Keep the checklist with the API's authentication configuration, not only in a one-time implementation document. For broader account security decisions, compare token-based authentication with passwordless authentication options and review how identity verification controls fit into the wider platform design.