How to Decode a JWT Token

JSON Web Tokens (JWTs) show up in OAuth login flows, API gateways, and session cookies. Each token has three base64url-encoded parts separated by dots: header, payload, and signature. Decoding reveals claims such as subject, expiry, and scopes—but decoding is not verifying. Anyone can read an unsigned or wrongly trusted payload; only signature validation with the issuer’s key proves integrity. Use local tools or /tool/jwt-decoder to inspect structure during debugging, never to bypass authentication. Support tickets often include a JWT screenshot—redact the signature segment before posting to public forums. When debugging mobile apps, capture the token from Charles or mitmproxy only on staging builds with test users. If payload contains PII, fix the issuer rather than normalizing decode in the client. Refresh tokens and access tokens decode similarly but carry different exp and scope—do not swap them in API clients. Multi-tenant SaaS apps often put tenant_id in claims; verify that value matches the subdomain before assuming a routing bug. Log decoded headers without logging full tokens in production log aggregators. Machine-to-machine tokens often omit profile claims present in user tokens—do not expect email in service JWTs. Rotate staging secrets when contractors leave even if production keys stayed safe; teams reuse HMAC secrets across environments too often. Document which claim your API gateway uses for tenant routing before you rename fields in the issuer. OAuth refresh flows may return opaque refresh tokens while access tokens stay JWT—label them in your debugger notes. When migrating auth providers, compare claim names old and new; aud string mismatches cause silent 403s after cutover weekend.

Split the token

Copy the JWT without the word Bearer. Count two dots separating three segments. If you see four segments, you may have pasted a JWE or malformed string. Paste into a decoder or run each segment through base64url decode separately in a script.

Header fields

The header JSON usually includes alg (algorithm) and typ (JWT). Unexpected alg values like none or HS256 when you expect RS256 are red flags in security reviews. Note kid if present—it selects which public key to fetch from the issuer JWKS endpoint.

Payload claims

Registered claims include exp (expiry Unix time), iat (issued at), aud (audience), and iss (issuer). Custom claims carry roles or tenant IDs. Compare exp to current time when debugging “401 after five minutes” reports. Time skew between servers can invalidate tokens briefly—check clock sync.

macOS and Linux terminal peek

For learning only, echo the middle segment, pad base64url, and decode with a short Python one-liner or jwt decode utilities. Do not log production tokens into shared shell history—use a throwaway file or decoder UI with history disabled.

Windows PowerShell note

Base64url padding differs from standard Base64. Dedicated JWT libraries or /tool/jwt-decoder avoid manual padding mistakes. Install-Module JWT is an option for PowerShell shops that decode frequently in support scripts.

Verify signatures properly

Decoding shows JSON; verification uses HMAC secret or RSA/ECDSA public key from the issuer. OpenID Connect stacks fetch JWKS automatically. Never accept alg=none in production validators. Rotate secrets when staff with HMAC knowledge leave.

Cookie and storage hygiene

Browser devtools Application tab may show JWTs in localStorage—XSS can exfiltrate them. HttpOnly cookies hide tokens from JavaScript but still need CSRF protections on state-changing routes. Decoding a stolen token does not tell you who stole it; rotate sessions after incidents.

FileToolsHub JWT decoder

Visit /tool/jwt-decoder, paste the token, and read header and payload tables. Use during integration testing when you need a second opinion on claim spelling. Redact tokens before sharing screenshots—they are credentials.

Final checks

Integration tests should use short-lived tokens from a staging issuer rather than copying production cookies. When claims look wrong, confirm the authorization server clock and your laptop clock both use network time—skew breaks exp validation before signature ever fails. Document expected aud and iss strings in your API README so support staff know which claim to inspect first.

FAQ

Is decoding a JWT a security breach? Payloads are base64, not encrypted—treat them as visible to anyone holding the token. Can I decode without the secret? Yes for payload/header; signature verification needs the key material.

Why is my token huge? Nested JSON, long scope lists, or embedded PII inflate size—prefer reference tokens for large claims. Should I paste customer JWTs into online tools? Use local decoding for real user data; scrub or use test tenants in browser tools.