Skip to content
TabShedKitsMy desk

Read a JWT: Claims, Expiry, and What Decoding Cannot Tell You

Updated 5 min readBy

Decode a JSON Web Token to inspect its claims and expiry, understand why a login fails, and learn why decoding is not verification.

JWT DecoderDecode and inspect JWT tokens
Open JWT Decoder
On this page
  1. The three parts
  2. Step by step
  3. Standard claims
  4. Troubleshooting a failing login with the decoder
  5. What decoding cannot tell you
  6. Using real tokens safely
  7. A short example
  8. Common questions

A login suddenly fails. The API says "token expired", or "invalid audience", or just "unauthorized". The token is a long string of three parts separated by dots, and it looks like nonsense. It is not: two of the three parts are plain JSON, just encoded. The JWT Decoder reads them, so you can see what the token claims and when it stops being valid. This guide explains how to read the result, and the one thing decoding can never tell you.

The three parts

A JSON Web Token is header.payload.signature.

  • Header: says how the token was signed: the algorithm (alg), such as HS256 or RS256, and the type (typ), usually JWT.
  • Payload: the claims: facts about the user and about the token itself.
  • Signature: a value computed from the first two parts and a secret or private key. It proves that nobody changed them.

The header and payload are encoded with base64url, not encrypted. Anyone who has the token can read them. That is why you should never put passwords, personal data or secrets in a payload. You can see the same encoding in the Base64 tool, which has a URL-safe option.

Step by step

  1. Paste the token. A leading "Bearer ", surrounding quotes and spaces are removed for you, so you can copy straight from an Authorization header.
  2. Choose Header, Payload or Signature to see that part: the header and payload as formatted JSON, the signature as encoded text.
  3. Read the cards on the right: Algorithm, Standard claims and Custom claims.
  4. If the token has an exp claim in the past, an Expired badge appears.

If the token is not made of three dot-separated parts, you see "JWT must have 3 parts separated by dots". A part that is not valid base64url gives "Invalid Base64 URL encoding". Most often the token was cut off when copied, or a line break was inserted into it.

Standard claims

ClaimMeaningCheck
iss (issuer)Who created the tokenDoes it match the identity provider your API trusts?
sub (subject)Who the token is about, usually a user IDIs it the user you expected?
aud (audience)Who the token is meant forDoes it include your API? A wrong audience is a frequent cause of rejection.
exp (expires)The time after which the token is invalidIs it in the past?
nbf (not before)The time before which the token is not yet validIs it in the future? That can happen when clocks differ.
iat (issued at)When the token was createdHow old is it?
jti (JWT ID)A unique ID for this tokenUsed to revoke or detect reuse

The time claims are Unix timestamps in seconds. The tool shows them as a date in your local time together with a relative description, for example how long ago it expired. For a raw number, the Timestamp Converter lets you check it against UTC.

Troubleshooting a failing login with the decoder

  • "Token expired". Look at exp. If it is in the past, the client needs a new token; check that your refresh logic runs. If exp is only a few minutes after iat, the lifetime is short on purpose.
  • "Token not yet valid". Compare nbf and iat with the current time. A difference of a few seconds between the issuer's and the server's clocks is a classic cause.
  • "Invalid audience" or "invalid issuer". Compare aud and iss with what your API expects, character by character: a trailing slash or a different domain breaks the match.
  • Missing permissions. Look at the custom claims, such as roles or scopes, and check that the claim your code reads exists under that name.
  • "Invalid signature". Decoding cannot find this, see below.

What decoding cannot tell you

The tool shows a warning, Signature not verified, for a reason. Decoding reads the header and payload; it does not check the signature. Anyone can create a token with any payload, put any text as the signature, and the decoder will display it happily. So a decoded token proves nothing about who issued it or whether it was changed. Verification needs the secret (for HS256) or the public key (for RS256 and similar), and belongs on your server, with a maintained library. Never make a decision in the browser based only on decoded claims.

Using real tokens safely

The token is decoded in your browser and is not uploaded. Still, a live token is a credential: anyone holding it can act as the user until it expires. Prefer decoding expired or test tokens, do not paste production tokens into chat or tickets, and do not share screenshots that show a whole token. If you did leak a token, revoke it or wait for its short expiry.

A short example

Suppose the payload contains an iat of 1763510400 and an exp of 1763514000. The difference is 3,600 seconds: the token lives for one hour. If your app received it two hours after iat, it is expired, whatever the signature says. If the payload also holds "aud": "api.example.com" but your API is configured for "example.com", a strict check will reject it even though the token is fresh. These two checks, time and audience, explain a large share of "my token worked yesterday" reports, and both can be read straight from the decoded payload without any secret.

Common questions

Is my token sent anywhere?

No. It is decoded in your browser.

Can the tool create tokens?

No, it only reads them.

Why are there no custom claims?

The payload contains only standard claims. The card says so.

My token has five parts.

That is an encrypted token (JWE), whose payload cannot be read without the key. This tool reads the common three-part signed tokens.