Guide · Updated July 2026

JWT decoding, claims and signature verification

A decoded token is readable, not trusted. Authentication systems must verify its signature and claims before accepting it.

The three compact segments

A common signed JWT has three period-separated segments: header, payload and signature. The first two are JSON encoded with Base64URL. The header commonly states a token type and signing algorithm. The payload contains claims. The signature lets a verifier detect changes using an allowed algorithm and the correct key. Encryption is a different JWT-related construction; ordinary signed JWT payloads are visible to anyone who receives the token.

Registered and application-specific claims

  • iss identifies the issuer that created the token.
  • sub identifies its subject.
  • aud identifies the intended audience.
  • exp is the expiration time; nbf is the earliest valid time.
  • iat records issue time and jti can identify a particular token.

These names do not enforce themselves. A verifier must check the issuer and audience expected by that service, reject expired or premature tokens, and apply application authorization rules. A role string in an unverified payload is only attacker-controlled text.

Why decoding is useful

Local decoding helps troubleshoot the shape of a token: confirm that the expected issuer is present, translate numeric dates, compare environments and spot a missing scope. It is also useful when a request is rejected and you need to distinguish an expired credential from a permission problem. It must not be used as the authorization decision itself.

What secure verification requires

  1. Accept only algorithms explicitly configured by the application; do not trust the header alone.
  2. Select a trusted key for the expected issuer and handle key rotation deliberately.
  3. Verify the cryptographic signature over the original encoded segments.
  4. Validate issuer, audience, expiration and not-before values with a small, documented clock tolerance.
  5. Apply scopes, roles and account state using server-side authorization rules.

Use a maintained JWT library for verification. Handwritten crypto and generic online decoders are unsuitable for production authorization. Avoid algorithm-confusion problems by keeping symmetric and asymmetric key configurations separate and rejecting unexpected algorithms.

Expiration and time mistakes

JWT numeric dates are Unix seconds, not JavaScript milliseconds. Treating exp as milliseconds can display a date near 1970; multiplying twice can produce a far-future date. Convert the value as UTC and then display a local representation if useful. A token can also be rejected before its visible expiry due to clock differences, revocation, issuer policy or an invalid audience.

Privacy checklist

Access tokens are credentials. Even if a payload appears harmless, the complete token may authorize requests. Do not paste production tokens into tickets, source control, analytics or third-party websites. The GenericTools.dev JWT Decoder runs in the browser, but you should still use a synthetic or expired token when demonstrating a problem and redact identifiers before sharing screenshots.

Typical troubleshooting questions

  • Does the token contain exactly three non-empty segments for the signed compact form?
  • Do iss and aud exactly match the API configuration?
  • Are exp and nbf interpreted as seconds and compared in UTC?
  • Was the correct environment and signing key used?
  • Is the request missing the expected Bearer authentication scheme?

Inspect a JWT locally → · All developer guides