JWT Decoder Guide: How to Read Claims, Verify Tokens, and Debug Authentication Errors

Overview

JSON Web Tokens, usually called JWTs, are compact strings commonly used to carry authentication and authorization data between a client and an API. A token typically looks like three Base64URL-encoded sections separated by periods:

header.payload.signature

The first section describes the token and its signing method. The second contains the claims, such as the subject, issuer, audience, and expiration time. The third is a cryptographic signature calculated from the first two sections.

A JWT decoder can Base64URL-decode the header and payload so you can inspect their JSON content. That makes a decoder useful when debugging an API request, checking whether a token contains expected claims, or investigating why a session was rejected. However, anyone who possesses a token can usually decode its header and payload. The decoded information should not be treated as trustworthy until the signature and validation rules have been checked.

Do not paste production access tokens into an online tool unless your organization permits it and you understand how the tool handles input. For sensitive tokens, use a local utility or a trusted development environment. You can also review related utilities in this directory of online developer tools.

Core framework

1. Decode the header

The header is JSON after Base64URL decoding. It commonly includes an alg value identifying the signing algorithm and a typ value indicating the token type. Some systems also include a key identifier, often represented by kid, which helps a verifier select the correct public key.

For example, a decoded header might look like this:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "key-2026-01"
}

The header is informative, not authoritative. A server must not blindly accept whichever algorithm the token declares. The verifier should enforce an allowed algorithm list and use the expected key type.

2. Inspect the payload claims

The payload contains claims. Registered claim names often include:

• sub: the subject associated with the token, such as a user or service identifier.
• iss: the issuer that created the token.
• aud: the intended recipient or audience.
• exp: the expiration time, represented as a Unix timestamp.
• nbf: the time before which the token should not be accepted.
• iat: the time at which the token was issued.
• jti: an optional identifier for the individual token.

Applications can also add custom claims, such as roles, scopes, tenant identifiers, or feature flags. A claim’s presence does not automatically make it valid. Your application must define which claims are required and how their values are interpreted.

3. Understand verification

Verification checks whether the signature matches the token’s header and payload using the expected cryptographic key. It should normally be combined with validation of the token’s claims. A robust verification process generally checks:

• the signature using a trusted secret or public key;
• the permitted signing algorithm;
• the expected issuer;
• the expected audience;
• the expiration time and, where applicable, the not-before time;
• required claims, scopes, and application-specific permissions.

For symmetric algorithms, such as an HMAC-based method, the verifier uses a shared secret. For asymmetric algorithms, such as an RSA- or elliptic-curve-based method, the issuer signs with a private key and the API verifies with a corresponding public key. A decoder does none of this by itself. It only makes encoded data readable.

Practical examples

Debugging an expired token

If an API reports that a token is expired, decode the payload and inspect exp. Convert the Unix timestamp to a human-readable time, then compare it with the server’s clock. Check the environment as well: a token issued for a local, test, or staging system may have a different lifetime or issuer than the production API expects.

Clock differences can also affect exp and nbf. A small, explicitly configured tolerance may be appropriate for distributed systems, but it should not be used to conceal a substantial time or configuration problem.

Diagnosing issuer and audience failures

A valid signature does not mean that every service should accept the token. If the API expects an issuer such as an identity provider URL but the token contains a different iss value, issuer validation should fail. Likewise, an access token intended for one API may contain an aud value that does not match another API.

Compare the token claims with the verifier’s configured values, including exact spelling, capitalization, and URL formatting. Also confirm that the client requested a token for the intended resource or audience.

Using a decoder alongside other tools

When a token is part of a larger API debugging session, format the decoded JSON with a JSON formatter and validator. This makes nested claims easier to inspect and helps distinguish malformed JSON from a valid but unexpected value. If two decoded tokens differ, a JSON diff tool can highlight changed claims without requiring a manual comparison.

For a local JavaScript inspection workflow, treat decoding as a display operation and use a maintained JWT library for verification. Keep verification configuration close to the service that consumes the token, rather than relying on a browser-only check or a client-side decoder.

Common mistakes

• Confusing decoding with verification. Readable claims prove only that the token has a decodable structure. They do not prove who issued it or whether it is still valid.
• Trusting client-side authorization. A frontend can decode a token to display UI state, but permission decisions must be enforced by the server that protects the resource.
• Accepting any algorithm. The verifier should use an explicit allowlist appropriate to the deployment and key configuration.
• Skipping issuer or audience checks. A signature from a trusted issuer can still belong to a different application or API.
• Logging complete tokens. Access tokens are credentials in many systems. Redact them in logs, screenshots, issue reports, and support messages.
• Assuming claims are always strings. Values such as aud may be represented differently across implementations. Validate the expected type and handle the documented form.
• Using a stale signing key. If keys rotate, the verifier may need a current key set and a way to select the key identified by the header.

When to revisit

Revisit your JWT debugging process whenever the identity provider, API gateway, signing keys, token library, or authorization configuration changes. It is also worth reviewing when an application moves between environments, introduces a new audience, changes token lifetimes, or begins using new scopes and roles.

For a practical checklist, start by preserving the exact HTTP status and server error, then inspect the token header and claims without sharing the token. Confirm the expected algorithm, issuer, audience, expiration, and key identifier. Next, verify the signature with the service’s configured key and reproduce the request against the correct environment. Finally, remove sensitive token values from logs and record only the non-secret facts needed to explain the failure.

Use a JWT decoder as an inspection aid, not as an authentication mechanism. That distinction keeps debugging efficient while preserving the security boundary between understanding a token and trusting it.