JWT Decoding Explained: What Developers Can Learn from a Token
JSON Web Tokens, better known as JWTs, appear almost everywhere in modern web development. They are commonly used when applications need to exchange claims about a user, session, service, or authorization request in a compact format.
A JWT can look intimidating at first:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IlRlc3QgVXNlciIsImlhdCI6MTcxMDAwMDAwMH0.example-signature
It may look like an encrypted string, but an important detail is often misunderstood: simply decoding a typical signed JWT does not mean breaking encryption.
The header and payload are normally Base64URL-encoded, which means developers can inspect their contents without knowing the signing secret.
Understanding that distinction is important when debugging authentication systems.
Understanding the Three Parts of a JWT
A commonly encountered signed JWT contains three sections separated by periods:
header.payload.signature
Each section serves a different purpose.
Header
The header normally describes information about how the token is protected.
A decoded header might look like this:
{
"alg": "HS256",
"typ": "JWT"
}
The alg value indicates the cryptographic algorithm associated with the token, while typ identifies the token type.
Payload
The payload contains the claims carried by the token.
For example:
{
"sub": "1234567890",
"name": "Test User",
"role": "editor",
"iat": 1710000000,
"exp": 1710003600
}
These claims could describe the user, when the token was issued, when it expires, or application-specific information.
Signature
The third section is used to protect the integrity of a signed token.
Its purpose is very different from the payload.
A valid signature allows the receiving application to determine whether the signed data has been altered and whether it was signed using the expected key or credentials.
That leads to one of the most important JWT concepts.
Decoding Is Not the Same as Verification
Imagine receiving a JWT from an API and decoding its payload.
You might see:
{
"role": "admin"
}
That does not automatically mean the user should be treated as an administrator.
Anyone who understands the JWT structure can potentially create or modify encoded header and payload data.
The application must still verify the token according to its authentication and security requirements before trusting the claims.
So these are two different operations:
Decoding means reading the information contained in the token.
Verification means checking whether the token's protection is valid and whether the token should be trusted.
This distinction matters during debugging because developers often need to inspect a token without necessarily verifying it.
Why Developers Decode JWTs
JWT decoding is particularly useful when troubleshooting authentication problems.
Suppose a user reports that they are suddenly being logged out of an application.
The token might contain:
{
"sub": "user_4582",
"iat": 1760000000,
"exp": 1760003600
}
Inspecting the exp value could reveal that the token has already expired.
In another situation, an API might reject a request because the token contains an unexpected audience, issuer, or role.
Instead of debugging the entire authentication system blindly, inspecting the payload can quickly reveal what information was actually issued.
JWT decoding is therefore useful for:
debugging API authentication,
checking token expiration,
inspecting user or role claims,
examining issuer and audience values,
testing authentication flows,
comparing tokens between environments,
and understanding what an identity provider is sending.
Common JWT Claims Developers Should Recognize
Several claim names appear frequently in JWT implementations.
sub — Subject
The subject normally identifies the entity the token refers to.
For example:
"sub": "user_4582"
iss — Issuer
The issuer identifies the entity that issued the token.
"iss": "https://auth.example.com"
aud — Audience
The audience indicates who or what the token is intended for.
"aud": "inventory-api"
exp — Expiration Time
The expiration claim indicates when the token should no longer be accepted.
"exp": 1760003600
iat — Issued At
This indicates when the token was issued.
"iat": 1760000000
nbf — Not Before
This indicates a time before which the token should not be accepted.
These time-based values are generally represented using Unix-style numeric timestamps, which can make them difficult to interpret by simply reading the raw JSON.
A decoder that converts or explains these values can therefore make troubleshooting much faster.
A Practical Debugging Example
Imagine a frontend application successfully authenticates a user, but every request to an API returns:
401 Unauthorized
Instead of immediately assuming that the API is broken, the developer can inspect the JWT.
The payload might contain:
{
"sub": "4278",
"aud": "mobile-api",
"role": "user",
"exp": 1760003600
}
But the backend application expects:
aud: "web-api"
The token itself may be structurally valid, but it was issued for a different audience.
Finding that discrepancy by inspecting the token could save considerable debugging time.
The same approach works when investigating incorrect roles, expired tokens, unexpected issuers, or missing claims.
Be Careful Where You Paste Tokens
JWT debugging introduces another consideration: privacy.
Tokens may contain information about users, services, permissions, internal system identifiers, or authentication context.
Some tokens may also provide access to protected systems while they remain valid.
For that reason, developers should be cautious about copying real production tokens into unknown websites.
For quick inspection, the KRIYANO JWT Decoder decodes the token's header and payload locally in the browser. It also displays common time claims such as expiration and issued-at information. The tool is intended for decoding and inspection rather than signature verification.
Even with local tools, using sanitized or test tokens whenever possible is a good development habit.
Why the Payload Should Not Be Treated as Secret
One common misconception is that information placed inside a normal signed JWT payload is automatically hidden from users.
That is not generally true.
Because the payload of a typical signed JWT can be decoded, developers should avoid treating ordinary JWT payload fields as a secure place to hide sensitive information.
For example, placing something like this in a normal readable payload would be a poor design:
{
"username": "example",
"database_password": "secret-password"
}
A developer should assume that information contained in a normally encoded JWT payload may be inspected by whoever possesses the token.
Signing protects integrity; it does not automatically make the payload confidential.
Applications that require confidentiality need an appropriate encryption design rather than relying on Base64URL encoding.
JWTs Are Useful, but They Need Careful Handling
JWTs are popular partly because they provide a compact way to carry claims between systems.
However, their familiar three-part appearance can hide important security concepts.
Being able to decode a token is useful for debugging, but reading the payload tells you only what the token claims.
It does not prove that those claims are trustworthy.
Developers still need proper verification, algorithm handling, expiration checks, issuer validation, audience validation, and application-specific authorization rules.
That separation between inspection and trust is one of the most important concepts to understand when working with JWTs.
Final Thoughts
JWT decoding is a simple skill that can make authentication debugging considerably easier.
By examining the header and payload, developers can identify expiration problems, unexpected claims, incorrect audiences, issuer mismatches, and other configuration issues without treating the encoded token as a mysterious string.
Just remember the central rule:
Decoded does not mean verified.
Use decoding to understand what a token contains. Use proper verification and authorization logic before allowing your application to trust what it says.
This article was created with AI assistance and edited for clarity, accuracy, and readability.