Learn JWTs

JWT tutorial: decode, validate, and harden every token

This guide walks through the structure of a JWT, explains how to safely decode tokens with JWTSecrets, and documents the security checks you should automate in production.

Practical steps Zero server upload Includes security checklists

1. Understand the three parts of a JWT

JSON Web Tokens contain three Base64URL encoded segments separated by periods. The header defines metadata, the payload holds claims, and the signature ensures integrity.

Header

Includes lg (algorithm) and optional yp and kid. Reject lg: none unless you are tracing an exploit.

Payload

Contains registered claims like iss, sub, ud, exp, bf, and any custom scopes. Treat everything as attacker-controlled.

Signature

Protects integrity using HMAC (HS256) or asymmetric algorithms (RS256, ES256). Verification requires the correct key.

2. Decode tokens safely with JWTSecrets

  1. Copy the full token. Ensure you include all three segments. Missing padding or truncated signatures will raise errors.
  2. Paste into the JWT decoder. The tool runs locally, highlights the header and payload, and scores obvious security risks.
  3. Review highlighted issues. JWTSecrets flags missing exp, overlong lifetimes, bf in the future, and weak signatures.
  4. Share safely. Use demo links for synthetic tokens only. Production secrets must never leave your control.

Tip

You can preload a token by appending #t= followed by a Base64 encoded token to the decoder URL. The script decodes it locally on load.

3. Validate claims before trusting a token

After decoding the payload, confirm that claims align with your authentication policy. Use automated guards in your API and supplement with manual reviews during debugging.

Checklist

  • ✓ iss matches your identity provider.
  • ✓ ud matches the API or app that consumes the token.
  • ✓ exp and bf respect your clock skew and rotation policy.
  • ✓ Custom claims (scopes, roles) align with the user profile.

Automation ideas

  • Reject unsigned tokens at the gateway.
  • Pin acceptable algorithms ("RS256", "ES256", "HS512").
  • Use short lifetimes with refresh tokens and continuous reauthentication.
  • Emit structured logs for every token decision.

4. Harden your JWT pipeline

Decoding is just the first step. To protect sessions end-to-end, incorporate verification, rotation, and monitoring.

Verification checklist

  • Validate the signature using your signing key or JWKS endpoint.
  • Look up the token ID (jti) to detect revocation.
  • Confirm that scopes match the endpoint being accessed.

Monitoring best practices

  • Emit structured logs with sub, iss, and decision outcomes.
  • Alert on tokens with unusually long lifetimes or unusual audiences.
  • Create dashboards that compare token issuance to revocation events.

Next steps

Explore JWT examples

See how B2C, B2B, and machine tokens structure claims and how JWTSecrets scores them.

Add verification

Request JWTSecrets Enterprise to enforce algorithms, policies, and audit logs automatically.

Frequently asked questions

Does decoding require my secret key? ⌃

No. Decoding the header and payload does not require the signing key. Verification does, which is why JWTSecrets Enterprise integrates with managed HSMs.

Should I store tokens in localStorage? ⌃

Avoid it when possible. Use HttpOnly cookies for session tokens to prevent XSS access, and rotate refresh tokens frequently.

How long should exp be? ⌃

For interactive logins keep expirations under 15 minutes with automatic refresh. Machine tokens should expire in minutes and rely on client credentials for reissue.