The Logic Gate

logic-gate.dev

Security Utilities

JWT Debugger

Decode JWT header and payload JSON for inspection while keeping signature verification conceptually separate.

Valid Format

yes

Algorithm

HS256

Subject

device-42

Expires At

2030-01-01T00:00:00.000Z

{
  "alg": "HS256",
  "typ": "JWT"
}
{
  "sub": "device-42",
  "iss": "logic-gate",
  "exp": 1893456000
}

Decoding JSON Web Tokens Safely

A JSON Web Token, or JWT, is a compact string format commonly used to carry claims between systems. A token has three Base64URL-encoded sections separated by dots: header, payload, and signature. The header describes the token type and signing algorithm. The payload contains claims such as subject, issuer, audience, expiration time, issued-at time, roles, or application-specific data. The signature protects the header and payload from undetected modification when verified with the correct key.

This debugger decodes the header and payload so they can be inspected as JSON. It does not verify the signature. That distinction is essential. Decoding a JWT only reveals what the token says. Verification proves whether the token was signed by a trusted party and whether the protected content has not changed. Never treat a decoded token as trusted just because it parses successfully.

Manual Decoding Steps

To decode a JWT manually, split the token on dots. The first part is the header, the second part is the payload, and the third part is the signature. Base64URL differs from ordinary Base64 by using dash instead of plus, underscore instead of slash, and often omitting padding equals signs. Convert the Base64URL text back to bytes, decode those bytes as UTF-8, and parse the result as JSON. The signature section is binary data encoded the same way, but it is not useful to read as JSON.

A typical header might contain alg set to HS256 and typ set to JWT. A typical payload might include sub set to user-123, iss set to auth-service, and exp set to 1893456000. NumericDate claims such as exp, iat, and nbf are seconds since the Unix epoch, not milliseconds. To interpret an expiration manually, multiply by 1000 for JavaScript Date objects or use a timestamp converter that expects seconds. Confusing seconds and milliseconds can make a token appear to expire decades away or in 1970.

Verification Is Separate

JWT verification checks the cryptographic signature and validates claims. For HMAC algorithms such as HS256, the verifier uses a shared secret. For RSA or ECDSA algorithms such as RS256 or ES256, the verifier uses the issuer's public key. Verification should also enforce allowed algorithms, issuer, audience, expiration, not before time, and sometimes nonce or token-use claims. A token with a valid signature can still be unacceptable if it was issued for a different audience or is expired.

Algorithm handling is a common security boundary. Applications should not blindly trust the alg value in the token header. Instead, configure which algorithms are allowed for a given issuer and key. Historical JWT vulnerabilities often came from accepting "none" algorithms, confusing symmetric and asymmetric keys, or failing to validate audience and issuer. A debugger is helpful for inspection, but production verification belongs in a maintained security library with explicit configuration.

Claims and Privacy

JWT payloads are encoded, not encrypted, unless a separate JWE encryption format is used. Anyone who obtains a normal signed JWT can decode the payload. Do not place secrets, passwords, private keys, or sensitive personal data in a signed-only JWT. If a client stores a token, assume the client can read its claims. Use opaque tokens or encrypted tokens when the payload must remain confidential.

Common registered claims include iss for issuer, sub for subject, aud for audience, exp for expiration, nbf for not-before, iat for issued-at, and jti for token ID. Application claims may include roles, scopes, tenant IDs, device IDs, or feature flags. Keep payloads small because JWTs often travel in HTTP headers. Very large tokens can exceed proxy or server limits and increase request overhead.

Industry Applications

JWTs are used in web authentication, API authorization, single sign-on, service-to-service identity, IoT device sessions, and temporary access grants. Engineers debug them when login flows fail, APIs reject requests, clocks drift, key rotation breaks verification, or an audience claim does not match the resource server. Being able to inspect the header and payload quickly saves time, but the inspection must be paired with an understanding of trust boundaries.

When debugging, check the algorithm, key ID, issuer, audience, subject, expiration, not-before time, and clock skew. Confirm which system issued the token and which system is expected to verify it. If a token decodes but fails verification, inspect key rotation, JWKS caching, allowed algorithms, and whether the token has been copied with whitespace or line breaks. This tool is the first step: make the claims visible so the real verification path can be reasoned about clearly.

Treat decoded JWTs as sensitive during debugging. A bearer token may grant access to real systems until it expires or is revoked. Avoid pasting production tokens into third-party tools, screenshots, tickets, or chat logs. If a token must be shared internally, redact the signature and any private claims, or generate a test token with the same structure. Local decoding is useful because it lets engineers inspect format and claims without sending credentials outside the development environment.

Learning Focus

JWT Debugger becomes easier to trust after the article's main checkpoints are clear: Manual Decoding Steps, Verification Is Separate, Claims and Privacy, Industry Applications. The JWT workflow depends on header, payload, Base64URL segments, algorithm, and expiration claim, so the first study task is identifying where those values appear in timing, sampling, packet, encoding, waveform, or channel assumptions represented by header, payload, Base64URL segments, algorithm, and expiration claim.

For a quick classroom check on JWT, use this exercise: For JWT, build one small example with numbers simple enough to check by hand, then change one input and explain why the output moved. Follow it by changing one listed input, such as header, payload, Base64URL segments, algorithm, and expiration claim, and write the expected effect before using the tool again. The common JWT trap is forgetting that the displayed text follows a strict syntax or encoding convention rather than ordinary prose.

A complete study note for JWT should show the units, timing or encoding convention, one worked example, and the way header, payload, Base64URL segments, algorithm, and expiration claim affect the measured or decoded value. That makes the JWT answer reviewable because another student can see whether a mismatch came from the math, the convention, the setup, or the way an input was entered.