Decoding a JWT is not verifying it

A JSON Web Token (JWT) appears as three dot-separated strings. That appearance encourages a dangerous shortcut: because a browser can decode the first two strings, their contents must be trustworthy. They are not. Decoding inspects a token's declared structure. Verification is a security decision by a system that knows the expected issuer, audience, time policy, algorithm, and verification key. This guide uses a forged, non-production sample. It contains no account, secret, private key, or usable credential.

The problem

RFC 7519 defines the compact JWT serialization as base64url-encoded header, payload, and signature segments separated by periods. Base64url is an encoding, not encryption. Anyone holding the token can decode its first two segments, and an attacker can also write a new header and payload. The payload may say that a subject is an administrator, that it expires next year, or that it belongs to a familiar issuer. Those are assertions supplied by an untrusted input until verification has succeeded.

The distinction matters at every boundary where a token changes authorization. A debugging panel may decode a token locally to show a timestamp or a malformed claim. That panel must not use the decoded role, sub, or scope to decide what a visitor may do. Likewise, a frontend may display an expiry hint, but an API must make its own decision rather than accept a browser's interpretation. A signed token can be valid in one application and unacceptable in another because its intended audience differs.

Verification is not merely “check that there are three pieces.” A verifier uses a preconfigured trust relationship. It accepts a narrow set of algorithms, obtains a verification key through a controlled mechanism, verifies the signature over the original protected data, and evaluates claims according to local policy. RFC 8725 emphasizes that applications must not let attacker-controlled token content choose critical validation behaviour. A decoder has none of that context.

Worked example

Here is a syntactically valid demonstration token. Its header decodes to {"alg":"HS256","typ":"JWT"}. Its payload decodes to {"sub":"demo-user","role":"admin","exp":1893456000,"iss":"https://issuer.example.invalid","aud":"demo-api"}. The last segment is only the base64url text for the word “signature”; it was not calculated with a secret and proves nothing. It is intentionally forged.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkZW1vLXVzZXIiLCJyb2xlIjoiYWRtaW4iLCJleHAiOjE4OTM0NTYwMDAsImlzcyI6Imh0dHBzOi8vaXNzdWVyLmV4YW1wbGUuaW52YWxpZCIsImF1ZCI6ImRlbW8tYXBpIn0.c2lnbmF0dXJl

A decoder can split this text on periods, apply base64url decoding to the first two segments, and print fields. exp is a NumericDate: seconds since the Unix epoch, so a reader can convert it to a date for inspection. iss is the issuer identifier claimed by the token. aud names the recipient or recipients for which the token is intended. Seeing plausible values does not establish that the token came from that issuer, is meant for the current API, or remains acceptable now.

Imagine changing the payload text from demo-user to another subject or changing role from viewer to admin, then re-encoding it. The result still has three well-formed segments and still decodes cleanly. A proper verifier rejects it because the signature no longer matches the protected header and payload under the expected key. The example is useful precisely because it makes the failure visible: parsing succeeds while trust has not been established.

Procedure

Start by treating a token as sensitive operational data even when it is not a password. Do not paste a production bearer token into an unapproved website, ticket, chat, or screenshot. For local troubleshooting, use a controlled development token, redact identifiers, or inspect it in the environment where it was issued. Record only the minimum facts needed to reproduce an issue, such as the claim names, their types, and an expiry conversion.

For inspection, first confirm the compact form has exactly three nonempty segments. Decode the header and payload as UTF-8 JSON without interpreting them as authority. Note the declared alg, but do not let it select your server's validation policy. Check whether exp, nbf, and iat have the expected numeric form; check iss against the issuer you expected; and compare aud with the identifier of the resource receiving the token. These are diagnostic observations, not a pass result.

For authentication or authorization, send the original compact token to a trusted verifier. That verifier should have an explicit allowlist of acceptable algorithms and key types, a configured issuer, and a configured audience. It verifies the signature before relying on payload claims, rejects expired tokens according to its clock policy, and applies any needed checks for nbf, token type, subject, or application-specific authorization. Key discovery must itself be authenticated and scoped to the known issuer; it is not safe to fetch an arbitrary key location announced by an untrusted header.

Finally, distinguish identity validation from application authorization. A successfully verified token may establish who issued a claim, but an application still needs to decide whether that subject may perform the requested action. Apply least privilege, server-side authorization rules, and resource-specific checks after verification. Log outcomes without storing full bearer tokens. If a token fails, report a generic authentication result to the caller and keep detailed diagnostics only in protected operational logs.

Technical explanation

The signature segment is computed over encoded header and payload data, not over the JSON object after a decoder has reformatted it. That detail prevents a verifier from silently accepting changed whitespace, reordered fields, or substituted segments. With symmetric algorithms, the verifier and issuer share a secret; with asymmetric algorithms, the issuer signs with a private key and the verifier uses an authenticated public key. In both cases, possession of a readable payload is unrelated to possession of signing authority.

Claims are also contextual. RFC 7519 defines registered names but leaves application policy to the recipient. exp indicates a time after which the token must not be accepted, yet a system must decide its allowed clock skew. nbf indicates a start time. iss comparisons need an exact, configured identifier rather than a visual similarity test. aud can be a string or an array, and an API must require itself to be an intended recipient. A claim can be syntactically correct while still being wrong for the current request.

Algorithm confusion is a reason to configure rather than infer. A service that accepts whatever alg an input announces can be induced to use an inappropriate verification path. A service that mixes issuers without binding keys, audiences, and algorithms can accept a token from the wrong security domain. RFC 8725 recommends mutually exclusive validation rules for different JWT kinds and strict algorithm verification. These are server responsibilities; a generic decoder cannot know them.

Common failures

A common failure is treating a decoded payload as a session record. For example, a client reads role: admin and exposes a privileged route before the backend has verified the token. Hiding a button is not authorization, but it can still confuse users and leak application behaviour. Make every protected operation enforce authorization on the trusted side. Another failure is accepting an exp value only because it is in the future; a future date does not repair an invalid signature, issuer, audience, or token type.

Another mistake is logging complete tokens while diagnosing a decoding problem. Bearer tokens may grant access until they expire, so logs, analytics, error reports, and browser extensions become unnecessary exposure points. Redact tokens and avoid copying them into examples. It is also unsafe to rely on a public decoder to validate a production token: a display tool may be useful for format inspection, but it has no knowledge of private keys, approved issuer configuration, revocation policy, or the exact API that should receive the token.

Do not turn off signature validation to “make testing work.” Create a test issuer and test keys with separate configuration, short lifetimes, and limited permissions. Reject unsigned tokens unless a carefully designed, non-authentication format explicitly requires them; JWT libraries should not accept an algorithm downgrade simply because a header requested it. Test failed signatures, unexpected audiences, old timestamps, and wrong issuers as deliberately as the happy path.

Considerations

Choose token boundaries before choosing a library. Document which component issues tokens, which services verify them, which audiences exist, and how keys rotate. Use distinct audiences for distinct APIs when their privileges differ. Configure an issuer URI exactly and validate it consistently. If several token profiles are required, give each profile a separate validation rule rather than one permissive rule that guesses its purpose from optional claims.

Time handling deserves operational care. Synchronize server clocks, decide a small and documented skew, and monitor failures that indicate drift. Keep access-token lifetimes appropriate to the risk and support renewal or revocation patterns outside the decoder. A local display of exp can help a developer explain why a request failed, but only the verifier's time policy determines acceptance. Avoid assuming that a token remains valid because its displayed date looks recent in a different timezone.

Keep decoded data out of unnecessary client state. The client may need non-sensitive presentation information, but the server should be the authority for permissions and protected resources. When a browser stores a bearer token, its exposure depends on the storage and application threat model; decoding it does not reduce that exposure. A compact guide cannot select the right architecture, so involve security review when designing an identity boundary.

Limitations

This guide explains the conceptual boundary between decoding and verification. It does not provide a drop-in authentication configuration, a key-management design, or a guarantee that a particular JWT library is safe when misconfigured. Library APIs, key distribution, token profiles, browser storage, and incident requirements vary by system. Read the current documentation for the verifier you operate and test it with its actual issuer and audience settings.

JWTs are not required for every session or API design. Opaque tokens, server-side sessions, and other mechanisms can have different trade-offs. A valid signature also does not prove that a user is presently authorized for every action, that a device is uncompromised, or that a token has not been revoked by a separate system. Treat verification as one necessary control in a broader design.

Checklist

Before trusting a JWT, keep the original compact token and separate inspection from authorization. Decode header and payload only to diagnose structure; never treat visible claims as proof. Verify the signature in a trusted system using a configured algorithm allowlist and authenticated key source. Require the expected issuer and audience, evaluate expiry and not-before times with a documented clock policy, and apply server-side authorization afterward. Never publish or log live bearer tokens, never disable verification for convenience, and test altered signatures and claims as negative cases. Use RFC 7519 and RFC 8725 with current library guidance when implementing the verifier.