Intro
JSON Web Tokens (JWTs) are compact, URL-safe claim sets used between systems. A JWT can use JSON Web Signature (JWS) for integrity protection, JSON Web Encryption (JWE) for confidentiality, or nested signing and encryption. The familiar readable three-part form is a JWS, not every possible JWT.
The most important distinction is simple: anyone with a three-part JWS can Base64url-decode its protected header and payload. That does not make its claims trustworthy. Trust comes only after the receiving system verifies the cryptographic protection and applies its own issuer, audience, lifetime, and authorization policy.
A three-part JWS is not every JWT
A compact JWS has three dot-separated segments: protected-header.payload.signature. The first two are Base64url-encoded JSON. The protected header identifies parameters such as alg; the payload is the JWT Claims Set; and the last segment is a signature or MAC value. A verifier checks the protected header and payload against a trusted key and a locally allowed algorithm before relying on the claims.
A compact JWE has five dot-separated segments: protected-header.encrypted-key.iv.ciphertext.tag. Its payload is encrypted, so a three-part decoder cannot read it. Seeing three or five segments only identifies the compact serialization; it does not prove that a token is valid or safe to accept.
Decode is not verify
- Decoding reveals the header and payload; it does not prove who created the token.
- JWS verification checks a signature or MAC against a trusted key and a locally allowed algorithm. Do not let an untrusted header choose the accepted algorithm or key source.
- Applications should require and validate the issuer, audience, expiry, not-before, and other claims that their protocol needs. Registered claims are not automatically mandatory.
- Never put passwords, private keys, or sensitive secrets into a JWT payload merely because it is encoded.
Use the decoder as an inspection aid
The JWT Decoder & Builder can help inspect a three-part JWS during development or troubleshooting. Treat pasted tokens as sensitive credentials, even when the tool processes them locally, and never mistake a readable payload for an authenticated identity.
Tip: Use the JWT tool to inspect structure, then verify tokens inside your application with a maintained library and an explicit validation policy.
Read claims as input, not as authorization
A claims set may contain iss (issuer), sub (subject), aud (audience), exp (expiry), nbf (not before), iat (issued at), and jti (token ID), alongside application-specific claims. Time claims use the JWT NumericDate format: seconds since 1970-01-01T00:00:00Z, ignoring leap seconds. Their meaning and whether they are required depend on the application profile.
Decoding the first two segments only reveals what the token says. It does not establish that the issuer created it, that the audience is correct, or that it has not expired. A practical verification flow is: parse the token; allow only the algorithms and keys configured for the expected issuer; verify its cryptographic protection; validate required claims with a small, explicit clock tolerance; then authorize the requested action. Keep the issuer-to-key relationship in trusted configuration or trusted issuer discovery, not in a token-provided URL.
Operational trade-offs
JWTs are convenient when a service needs portable claims, but revocation and immediate permission changes require planning. Short expiry times, refresh-token rotation, server-side session state, or a deny-list may be appropriate depending on the threat model. Large tokens also increase request and cookie size, and putting confidential information in a signed-but-readable JWS payload is a disclosure risk.
Use HTTPS, protect refresh tokens, and avoid putting tokens in URLs, which can leak through browser history, referrers, and logs. Browser storage has trade-offs: tokens readable by page JavaScript can be exposed by XSS, while cookies that are not readable by JavaScript can reduce that exposure but need CSRF protections when the browser sends them automatically. A decoder is useful for troubleshooting a token you are authorised to inspect; it cannot establish validity.
A validation checklist
Check the expected token type, allowed algorithm, trusted key, issuer, audience, expiry, not-before time, clock tolerance, required claims, scopes, and the action being authorised. Reject unsecured alg: none tokens unless an explicit, isolated test scenario requires them. Log failures without logging complete tokens. Treat a successful decode as an observation, not an authentication result.
Practical takeaway
A three-part JWS can be decoded in seconds, but trust must be earned by the service that verifies it. Validate the cryptographic protection, issuer, audience, time claims, algorithm, and permissions, then plan expiry and revocation. Use the decoder for authorised troubleshooting and never paste production tokens into an untrusted site.
FAQ
Is a JWT encrypted?
A JWT can be signed (JWS), encrypted (JWE), or nested. The common three-part JWS form generally has a readable header and payload and protects integrity only when verified. An encrypted compact JWE has five segments and requires the appropriate decryption key.
Can I change a JWT payload?
You can edit the text locally, but a correctly implemented JWS verifier should reject the changed token because its signature or MAC no longer matches.
Should I store sensitive information in a JWT?
No. Keep payloads minimal and assume the contents of a signed JWT can be read by anyone who obtains it.
Why will a JWT decoder not read every token?
This decoder inspects the three-part compact JWS form. A five-part JWE is encrypted and needs the correct decryption key; it cannot be decoded as a readable header-and-payload token. Nested JWTs may require both decryption and verification in the order specified by the application.