JWT Tokens: Structure, Claims, and Debugging
JSON Web Tokens (JWTs) are everywhere - authentication, API authorization, SSO, webhooks. But when something goes wrong, you need to decode and inspect them. Here's everything you need to know.
JWT Structure
A JWT has three parts separated by dots:
Each part is Base64url-encoded JSON:
- Header - Algorithm and token type
- Payload - Claims (the actual data)
- Signature - Verification hash
Decoding a JWT
You can decode any JWT without the secret key - the payload is just Base64, not encrypted. Use our JWT decoder to inspect tokens instantly.
Header: Payload:Standard Claims
| Claim | Name | Purpose |
|---|---|---|
iss | Issuer | Who created the token |
sub | Subject | Who the token is about (usually user ID) |
aud | Audience | Who the token is intended for |
exp | Expiration | When the token expires (Unix timestamp) |
iat | Issued At | When the token was created |
nbf | Not Before | Token is not valid before this time |
jti | JWT ID | Unique identifier for the token |
Common Debugging Scenarios
"Token expired" errors
Check the exp claim. JWT expiration is a Unix timestamp (seconds since 1970-01-01). Convert it to a readable date:
Our JWT decoder shows human-readable timestamps automatically.
"Invalid audience" errors
The aud claim must match what your server expects. If your auth provider sets aud: "https://api.example.com"" but your server checks for "api.example.com", it will reject the token.
"Algorithm mismatch"
The header's alg field must match your server's configuration. Common algorithms:HS256 - HMAC with SHA-256 (shared secret)RS256 - RSA with SHA-256 (public/private key pair)ES256 - ECDSA with P-256 (smaller keys, same security)Clock skew
If iat is in the future or exp is off by a few seconds, you have clock skew between the issuer and verifier. Most JWT libraries accept a clockTolerance of 30-60 seconds.
Security Best Practices
- Never store sensitive data in the payload. JWTs are encoded, not encrypted. Anyone can decode them.
- Always verify the signature. Decoding is not validation. Use a library to verify the signature with your secret/public key.
- Set short expiration times. Access tokens should expire in 15-60 minutes. Use refresh tokens for longer sessions.
- Use RS256
overHS256in distributed systems. With RS256, only the auth server needs the private key - other services verify with the public key.
- Validate all claims. Check exp
,iss,aud`, and any custom claims your application requires.
Quick Decode
Paste any JWT into our JWT decoder to instantly see the header, payload, and claim details with human-readable timestamps. The decoding happens entirely in your browser - your tokens never leave your machine.