JWT Decoder Online: How to Inspect, Validate, and Troubleshoot JSON Web Tokens Safely

Overview

JSON Web Tokens (JWTs) are compact strings commonly used to carry claims between a client and an API. A token often appears in an HTTP Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

A JWT normally contains three Base64URL-encoded sections separated by periods:

header.payload.signature

The header describes the token and signing method. The payload contains claims such as an issuer, subject, audience, issue time, or expiration time. The signature is used to detect whether the signed data has been altered and, depending on the algorithm, to establish that it was produced by a party holding the appropriate key.

A JWT token decoder can display the header and payload without knowing the signing secret. That makes decoding useful for debugging, but it does not prove that a token is authentic, current, or authorized. Treat “decoded” and “validated” as separate operations.

JWTs are encoded, not automatically encrypted. Unless a separate encryption mechanism is being used, anyone who possesses a token may be able to read its payload. Do not place passwords, private keys, payment data, or other secrets in ordinary JWT claims.

Core framework

1. Decode the structure before investigating the error

When you decode a JWT, first confirm that it has the expected three-part shape. Then inspect the header for values such as alg and typ, and inspect the payload for claims used by your API. A typical payload might look like this:

{
  "iss": "https://identity.example.test/",
  "sub": "user-123",
  "aud": "orders-api",
  "iat": 1710000000,
  "exp": 1710003600,
  "scope": "orders:read"
}

Numeric date claims are generally represented as seconds since the Unix epoch. Compare them with the server's clock, not only with the time shown by your browser. A token can appear valid locally while being expired from the API's perspective if clocks differ or if the token is being tested in a different environment.

2. Understand the claims that affect acceptance

• exp indicates when the token should no longer be accepted.
• nbf indicates the time before which the token should not be accepted.
• iat records when the token was issued and can help identify stale or incorrectly cached tokens.
• iss identifies the expected issuer. The API should compare it with a configured value.
• aud identifies the intended recipient or service. An API may reject a validly signed token intended for another service.
• sub identifies the subject, often a user or service, but its exact meaning is application-specific.
• Scopes, roles, and permissions describe what the application may allow. They do not replace signature and time validation.

Not every claim is mandatory for every design, and claim names do not create security rules by themselves. The receiving service must define which claims it requires and how it interprets them.

3. Separate decoding, signature verification, and authorization

These checks answer different questions:

1. Decoding: What data is present in the token?
2. Signature verification: Was the token produced with the expected key and left unchanged?
3. Validation: Is the algorithm allowed, and are issuer, audience, time, and other constraints acceptable?
4. Authorization: Does the authenticated subject have permission to perform this specific action?

Use a maintained JWT library for verification rather than implementing cryptographic operations yourself. Configure an explicit allowlist of algorithms and the expected issuer, audience, and key source. Do not simply trust the algorithm named in an unverified header, and do not treat a successful decode as evidence that a request should be authorized.

4. Treat online tools as inspection aids

A jwt decoder online is convenient for a deliberately created test token or a redacted example. It is a poor place for a production access token, refresh token, administrative credential, or token containing personal information. Before pasting a token into any external utility, check whether it can be processed locally, remove or replace sensitive values, and follow your team's handling rules. If a live credential has been exposed, use the appropriate revocation or rotation process rather than assuming that deleting it from a browser is sufficient.

Practical examples

Inspecting a token with a small local script

For repeatable debugging, a local script can decode the first two sections without verifying the signature. The following Python example is intentionally limited to inspection:

import base64
import json


def decode_segment(segment):
    padding = "=" * (-len(segment) % 4)
    raw = base64.urlsafe_b64decode(segment + padding)
    return json.loads(raw)


token = "header.payload.signature"
header, payload, _ = token.split(".", 2)
print(json.dumps(decode_segment(header), indent=2))
print(json.dumps(decode_segment(payload), indent=2))

This code does not verify the signature and should not be used to authenticate a request. Its purpose is to reveal malformed JSON, unexpected claims, or a token issued for the wrong environment.

Diagnosing a 401 response

Start by capturing the exact request sent to the API. Confirm that the header is present, uses the expected Bearer format, and contains the current token rather than a stale value from local storage or an environment variable. Decode the token and compare exp, nbf, iss, and aud with the API configuration. Then inspect server logs for the verification failure, without logging the complete token.

A 401 response often indicates missing, malformed, expired, or unverifiable credentials. A 403 response can indicate that authentication succeeded but the subject lacks the required permission. The distinction depends on the API, so use the service's documented behavior and logs. For broader API troubleshooting, keep an HTTP status code reference nearby.

Diagnosing a 403 response

Once signature and time checks pass, inspect the application's authorization rules. Verify that the expected scope or role is present, that the subject is mapped to the correct account, and that the endpoint requires the permission you think it does. Do not fix a 403 by adding broader permissions blindly; confirm the intended access model first.

If the request fails only in a browser, separate token issues from transport issues. CORS configuration, cookies, preflight requests, and proxy behavior can prevent a credential from reaching the API. The CORS errors guide provides a useful companion checklist.

Common mistakes

• Confusing Base64URL with encryption: Decoding a payload does not reveal a secret-protected message.
• Trusting client-side claims: UI code can display claims, but the API must independently verify and authorize every protected request.
• Ignoring audience and issuer: A valid token from one service or environment may be inappropriate for another.
• Using a permissive algorithm configuration: Restrict verification to the algorithms and key types your application explicitly supports.
• Assuming a long expiration is harmless: Longer-lived access tokens increase the period in which a stolen token may remain useful. Choose lifetimes and refresh behavior deliberately.
• Logging complete tokens: Request logs, browser history, screenshots, and issue trackers can become credential leaks. Redact tokens and sensitive claims.
• Testing only the happy path: Include expired tokens, wrong audiences, missing scopes, malformed segments, and key-rotation scenarios in API tests.

JWT validation is configuration-sensitive. If the token looks correct but verification fails, compare the key identifier, issuer metadata, environment variables, server clock, and deployed configuration. A JSON schema validator can help check the shape of decoded application data, but schema validation alone does not authenticate a JWT; see the JSON Schema validator tools comparison for related data-validation workflows.

When to revisit your JWT debugging process

Revisit this workflow whenever your identity provider, API gateway, signing algorithm, key-management process, or token claims change. It is also worth reviewing after a migration between development and production, a change to domain or issuer URLs, a new audience, or an incident involving exposed credentials.

Make the process actionable by keeping a redacted test token for each supported environment, documenting required claims, and recording the expected response for authentication and authorization failures. Add automated tests for expiration boundaries, clock tolerance, issuer and audience mismatches, invalid signatures, unavailable keys, and insufficient scopes. Review observability as well: logs should identify the validation failure and request context without storing bearer credentials.

For local API work, use HTTPS where the environment requires it and avoid copying real credentials into ad hoc tools. A local certificate workflow such as the one described in the local HTTPS setup guide can help reproduce secure transport conditions without moving production tokens into a third-party decoder. The safest lasting habit is simple: decode to understand, verify with a trusted library, authorize on the server, and handle every token as sensitive data.