Learn how JWT claims work, explore registered, public, and private claims, and discover security best practices for implementing JSON Web Tokens in your applications.
I've been using JWTs for years, but it wasn't until a production incident at Šikulovi s.r.o. that I really understood how claims work. We had tokens that stopped working randomly - turned out our clock was 90 seconds ahead of the auth server, and we weren't accounting for clock skew in our exp validation. Three hours of debugging for a 90-second offset.
Claims are just the data inside a JWT - who you are, what you can do, when the token expires. Simple concept, lots of ways to mess it up. Here's what I've learned the hard way about getting them right.
A JWT is three parts separated by dots: header.payload.signature. The payload is where your claims live. Everything is Base64URL encoded, so you can decode and read it (yes, anyone can read your claims - they're signed, not encrypted).
These are the 'official' claims defined in RFC 7519. You don't have to use all of them, but you should probably use most of them. I always include exp, iat, and sub at minimum.
Beyond the registered claims, you'll add your own. The spec distinguishes between 'public' claims (registered with IANA or namespaced with URIs) and 'private' claims (whatever you want). In practice, most of us just use private claims and hope we don't collide with anything.
exp, iat, nbf - these three time claims cause more production issues than everything else combined. They're all Unix timestamps (seconds since 1970), and the most common mistake is forgetting about clock skew between servers.
After building auth for dozens of projects at Šikulovi s.r.o., here's what I actually put in different token types:
After one security audit that found we were putting user emails in tokens (not a huge deal, but not great either), I made a checklist. Now I follow it religiously:
This confused me for years. HS256 uses a shared secret (same key signs and verifies). RS256 uses public/private keys (private signs, public verifies). If only one service creates and validates tokens, HS256 is simpler. If multiple services need to validate, RS256 is better because you don't have to share secrets.
I used to set tokens to expire in 24 hours because logging in frequently annoyed me. Then I realized: if a token is stolen, the attacker has 24 hours to use it. Now I use 15-minute access tokens with 7-day refresh tokens. Users stay logged in, but stolen access tokens are useless quickly.
Here's the dirty secret of JWTs: they're stateless, which means you can't really revoke them. Once issued, a token is valid until it expires. This bit me when a user reported their account was compromised and I realized I couldn't force logout. Here's how I handle it now:
Every API endpoint that accepts JWTs runs through this checklist. I've seen too many apps that only check the signature and skip everything else.
I've done security reviews for a lot of apps, and these JWT mistakes show up constantly. If you're making any of these, fix them today:
The localStorage vs cookie debate comes up constantly. Here's my take: for web apps, HttpOnly cookies win. They're invisible to JavaScript, which means XSS can't steal them. Yes, you need CSRF protection, but that's solvable.
Token validation failing? Here's my debugging flow. I built the JWT Decoder tool specifically because I was tired of copy-pasting tokens into random websites to debug them.
Registered claims are predefined by the JWT specification (like exp, iss, sub) and have standard meanings. Private claims are custom claims you define for your application (like user_id or role). Registered claims ensure interoperability, while private claims let you include application-specific data.
JWTs are signed, not encrypted by default. Anyone can decode and read the payload. If you need to hide claim values, use JWE (JSON Web Encryption) or avoid putting sensitive data in claims entirely. For most applications, signing alone is sufficient when combined with HTTPS.
Access tokens should be short-lived, typically 15-60 minutes. Refresh tokens can be longer (days to weeks) but require secure storage and revocation capability. Shorter expiration times limit the damage if a token is compromised.
A stolen JWT can be used by an attacker until it expires. This is why short expiration times are important. Implement token revocation through blacklists or refresh token rotation. Also use secure storage (HttpOnly cookies) to prevent theft through XSS.
No. JWTs are immutable once signed. Any modification to the header or payload invalidates the signature. To change claims, you must issue a new token with the updated values.
The sub (subject) claim is the registered claim for identifying the principal. Using it ensures interoperability with libraries and services that expect standard claims. You can still use custom claims like user_id alongside sub if needed.
Use refresh tokens to obtain new access tokens before expiration. Implement token refresh logic that detects near-expiration and refreshes proactively. Handle 401 responses by attempting refresh before prompting for re-login.
There is no hard limit in the specification, but JWTs are sent with every request (often in headers). Keep the total JWT size under 8KB to avoid issues with header size limits in servers and proxies. Minimize claims to essential data only.
Founder of CodeUtil. Web developer building tools I actually use. When I'm not coding, I experiment with productivity techniques (with mixed success).
SQL injection is still the #1 web attack. Learn the real difference between escaping and parameterized queries — with code examples in Python, PHP, and Node.js — and why one method leaves you exposed.
Learn why password hashing matters, why MD5 is broken for security, how SHA-256 differs, and why bcrypt and Argon2 are the right choice for storing passwords. Understand rainbow tables, salting, and modern best practices.
Understand JSON Web Tokens (JWT) from the ground up: how they work, their three-part structure, when to use them, security best practices, refresh token strategies, and common implementation mistakes to avoid.