How JWTs Work and How to Decode One Safely
6 min read · Published October 14, 2026 · Updated October 14, 2026
A login request fails with a 401, and the only clue is a long string starting with eyJ. Somewhere inside it are the user, the expiry time, and the permissions your code is checking, but the text looks like noise. Knowing how to read it turns a vague auth bug into a specific one, such as a token that expired twenty minutes ago.
This guide explains the structure of a JSON Web Token, what the standard claims mean, why decoding a token is not the same as trusting it, and how to look inside one without handing a live credential to someone else.
The three parts of a token
A JWT is three pieces of text joined by dots: header, payload, and signature. The header and payload are small JSON objects. The header describes the token, typically naming the signing algorithm in a field called alg and the token type in typ. The payload carries the claims, which are statements about the user or session. The signature is a value computed from the first two parts and a secret or private key.
Here is a short example, shown with line breaks for readability. In a real token the dots are the only separators and there is no whitespace.
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
.eyJzdWIiOiIxMjM0IiwiaWF0IjoxNzAwMDAwMDAwLCJleHAiOjE3MDAwMDM2MDB9
.<signature bytes, also encoded>Base64URL is encoding, not encryption
Each part is written in Base64URL, a variant of Base64 that swaps the plus sign for a hyphen and the slash for an underscore, and usually drops the trailing equals signs. These changes keep the token safe to place in a URL or an HTTP header.
The point to remember is that Base64URL is a reversible encoding. Anyone holding the token can turn the first part back into {"alg":"HS256","typ":"JWT"} and the second into the claims, with no key at all. A standard signed token provides integrity, not secrecy. Do not put passwords, full payment details, or anything you would not want the holder to read inside the payload. Encrypted tokens exist as a separate format, but the ones most people meet day to day are only signed.
Header : {"alg":"HS256","typ":"JWT"}
Payload : {"sub":"1234","iat":1700000000,"exp":1700003600}The common claims and what they mean
Claims are just keys in the payload. A handful have standard meanings, and you will see them in most tokens. Applications add their own, such as a role or an email address.
- iss, the issuer: who created the token, often a URL for the identity service.
- sub, the subject: who the token is about, usually a stable user identifier.
- aud, the audience: which service the token is intended for. A service should reject tokens meant for another audience.
- exp, expiration time: after this moment the token must not be accepted.
- iat, issued at: when the token was created.
- nbf, not before: the token is not valid until this moment.
Reading expiry timestamps
The time claims are Unix timestamps: the number of whole seconds since January 1, 1970 at 00:00 UTC. That is why exp looks like 1700003600 instead of a date. In the example above, iat is 1700000000, which is November 14, 2023 at 22:13:20 UTC, and exp is 3,600 seconds later, so the token lived for exactly one hour and expired at 23:13:20 UTC.
Two mistakes cause many expiry bugs. The first is mixing seconds and milliseconds. JWT time claims are in seconds, but some programming environments report the current time in milliseconds, which is a number about a thousand times larger. A token whose exp is accidentally in milliseconds appears to expire thousands of years from now. The second is clock drift: if the machine checking the token has a clock a minute off, a fresh token can look not-yet-valid or already expired. Many systems allow a small leeway of a few seconds to a minute for this reason.
To convert a claim into a readable date, the ELDOSA Unix Timestamp Converter shows seconds, milliseconds, and an ISO date for a value or for the current time.
Decoding is not verifying
Decoding means reading the header and payload. Verifying means recomputing the signature with the right key and confirming it matches, then checking the claims: is the issuer expected, is the audience yours, has the token expired. Only verification tells you the token is genuine and unmodified.
Because the payload is readable by anyone, an attacker can write any payload they like. What they cannot do, without the key, is produce a signature that verifies. So any decision based on a token, such as granting access, must happen on a server that has verified the signature with a library, using an algorithm it chose in advance rather than one the token's header requests. Treat everything you see in a decoded payload as unverified until that has happened.
A decoder is still very useful for debugging. It answers questions like which user does this token claim to represent, which audience was requested, and when does it expire, without proving anything about authenticity.
Inspecting a token without leaking it
A valid access token is a credential. Until it expires, whoever holds it can usually act as the user, so pasting a production token into a website that sends it to a server for processing creates a copy you cannot recall. The sensible habit is to use a decoder that works entirely in your own browser, and, where possible, to inspect tokens from a test environment or ones that have already expired.
The ELDOSA JWT Decoder reads the payload section in your browser and does not verify the signature. The decoding step is plain Base64URL and JSON parsing, so there is no reason for the token to leave your device, and the tool does not send it anywhere. If you still need to share a token in a bug report, remove the signature, which is the final segment, or redact the claims you do not need to show. A token without a valid signature cannot be used to authenticate.
Tools mentioned in this guide
Frequently asked questions
Why does my JWT start with eyJ?
The first part is a JSON object that begins with an opening brace and a double quote. Those characters, once Base64 encoded, always produce the letters eyJ, so almost every JWT header starts that way. It is a handy way to recognize a token.
Can I change a claim and keep the token working?
Not if the server verifies the signature. Changing any character of the header or payload changes what the signature should be, so verification fails. This is the main protection a signed token offers against tampering.
What is the difference between HS256 and RS256?
HS256 uses one shared secret both to sign and to verify, so every verifier must hold that secret. RS256 uses a private key to sign and a public key to verify, so many services can verify tokens without being able to create them.
How long should a token live?
There is no single right answer. Access tokens are often short, from minutes to an hour, which limits damage if one leaks, while refresh mechanisms issue new ones. The right lifetime depends on how sensitive the resource is and how your application handles sign-in.