You send a request with a token you know is fresh, and the API gateway answers 401 Unauthorized with Invalid Token. Your credentials are fine, so something inside the token is not. Paste it into a jwt decoder and the cause usually shows up in seconds: a dead exp, the wrong aud, an unexpected alg.
A JSON Web Token (JWT) is a compact, URL-safe container for claims passed between two parties. It is three Base64URL-encoded chunks separated by dots: header, payload, signature. The server issues it after login, and the client sends it back on every request in an Authorization: Bearer header.
Because the first two parts are plain encoded JSON, you can inspect a json web token in a few seconds. That is why most engineers keep an online jwt decoder bookmarked to decode jwt online whenever a gateway rejects a request. One caution before you paste anything: a live token is a credential. Use test tokens or a local tool for anything production-grade.
Quick-Reference JWT Anatomy Table
Every JWT you meet follows this layout. Keep it next to your jwt decoder when you read your first token of the day.
| Segment | Position / Typical Colour | Format | Key Fields Contained |
| Header | Part 1 (commonly shown red) | Base64URL-encoded JSON | alg (signing algorithm), typ (token type, usually JWT), often kid (key ID) |
| Payload | Part 2 (commonly shown purple) | Base64URL-encoded JSON | Claims such as sub, iss, aud, exp, iat, nbf, plus custom claims like scope or roles |
| Signature | Part 3 (commonly shown blue) | Base64URL-encoded binary, not JSON | HMAC or RSA/ECDSA signature over header.payload |
The colours are a convention from popular debugger tools, not part of the spec. Here is a decoded payload for reference:
json
{
“sub”: “user_8841”,
“iss”: “https://auth.example.com/”,
“aud”: “reporting-api”,
“iat”: 1767222000,
“exp”: 1767225600,
“scope”: “reports:read”
}
That exp value is 1 January 2026, 00:00 UTC. That date has already passed, so any gateway validating this token will return a 401.
Decoding vs. Verifying: What a JWT Decoder Can and Can’t Tell You
Any jwt decoder can read the payload without a key, because Base64URL is an encoding, not encryption. Decoding means splitting on the dots and reversing the encoding. No secret is involved. You can base64url decode token segments yourself in a shell:
bash
decode() {
local s=$(echo -n “$1” | tr ‘_-‘ ‘/+’)
case $(( ${#s} % 4 )) in 2) s=”$s==”;; 3) s=”$s=”;; esac
echo -n “$s” | base64 -d
}
decode “$(echo “$TOKEN” | cut -d. -f2)”
Verification is a different job. To verify jwt signature data, you recompute or check the signature with the right key and confirm it matches the third segment:
- HS256 and friends (HMAC): the issuer and the verifier share one secret.
- RS256, ES256 (asymmetric): the issuer signs with a private key, and you verify with the public key. In OIDC setups you usually fetch it from the issuer’s jwks_uri and match the token’s kid.
The rule that follows is simple. Never make an authorization decision from a payload you have only decoded. An attacker can write any payload they like. Only a successful signature check proves the data is untampered. It is also why pasting production tokens into random websites is a bad habit.
Reading JWT Payload Claims in Your JWT Decoder Output
Most 401s come down to one of these standard claims.
exp (expiration time). It is a Unix timestamp in seconds, not milliseconds. Mixing the two makes tokens look expired in 1970 or valid for thousands of years. Convert it with date -u -d @1767225600 and compare it with the current time.
nbf (not before) and iat (issued at). When the issuer’s clock runs a few seconds ahead of the validator’s, a brand-new token gets rejected as “not yet valid”. Allow 30 to 60 seconds of leeway in your validation library, and keep NTP running on your containers and VMs.
sub, iss and aud. sub identifies the subject, usually a user or service ID. iss is the issuer, and aud is who the token is meant for, as either a string or an array. These must match what the API expects exactly. A trailing slash on the issuer URL is enough to fail validation.
How a JWT Decoder Pipeline Fits an SEO Operations Stack
Take a link-building and reporting operation such as Links Builder Hub as a working example of where token handling gets real. A platform like this pulls ranking and backlink data from third-party SEO APIs, passes work between internal microservices and pushes results to client dashboards through webhooks. Every hop carries a bearer token, and every token has a lifetime.
A dependable jwt decoder step in that pipeline lets automated workers read exp, aud and scope claims before a job runs. The pattern looks like this:
- Before scheduling a crawler or reporting task, the worker reads the token’s claims locally and checks the remaining lifetime.
- If less than a safety window remains (five minutes is a common choice), it refreshes the token first, so a long job does not die halfway with a 401.
- It checks that aud and scope match the job, so a token minted for the reporting API cannot be used against the crawler queue.
- Inbound webhooks and dashboard calls get a full signature check with a proper library before any claim is trusted.
That last point is the one to remember. Decoding is for planning on tokens you already hold, such as lifetime and scope hints. Trust decisions come from verification.
4 Dangerous JWT Security Flaws Developers Must Watch For
1. The alg: “none” vulnerability
The spec allows unsigned tokens with alg set to none. A library that honours whatever the header says will accept a token with no signature at all. Keep a server-side allowlist of algorithms and reject none outright.
2. Algorithm confusion attacks
Your server expects RS256 and holds a public key. An attacker changes the header to HS256 and signs the token using that public key, which is public, as the HMAC secret. A naive library feeds the same key into the HMAC check and accepts it. The fix is to pin the algorithm per key and use libraries that bind key types to algorithms.
3. Sensitive plain text inside claims
Anyone can decode the payload, so passwords, PII and card data never belong there. If you need confidentiality, use an opaque reference ID or encrypted tokens (JWE) instead.
4. Token leakage through URL query parameters
A token in a URL ends up in server logs, browser history, proxy logs and Referer headers. Always send it in the Authorization header.
Debugging a 401 Step by Step with a JWT Decoder
Run the failing token through a jwt decoder first, then work down this list:
- Check the header. Is alg what the API expects? Does kid exist in the issuer’s current key set?
- Check exp. Convert it and compare it with the current time on the validating server.
- Check nbf and iat. If they are a few seconds in the future, suspect clock skew.
- Match iss and aud exactly. Look for trailing slashes, wrong environments (staging versus production) and array versus string differences.
- Check scopes or roles. The token may be valid but lack the permission the endpoint needs, which should be a 403, though some gateways return 401.
- Verify the signature with the right key. A rotated signing key or a kid mismatch is a classic cause.
- Check the transport. Confirm the header is exactly Authorization: Bearer <token>, with no quotes, stray whitespace or truncated characters.
Conclusion
Keep access tokens short-lived (5 to 15 minutes is a sensible range) and rotate refresh tokens with reuse detection, so a leaked token has a small window of usefulness. For storage, HttpOnly, Secure, SameSite cookies keep JavaScript away from the token, so an XSS bug cannot read it. localStorage is readable by any script on the page, though cookies need CSRF protection in return. Keep a jwt decoder handy for diagnosis, but remember that it only reads. Your server must verify every token it trusts.
