Custom Claims and Payload Design
You'll learn how to extend JWTs with application-specific data while keeping them lean and secure.
Beyond Standard Claims
While standard JWT claims (iss, sub, exp, iat) provide essential identity information, real applications often need custom data. Custom claims let you embed application-specific information directly in the token—like user roles, permissions, or preferences—without requiring additional database lookups on every request.
Think of a JWT like a backstage pass at a concert. Standard claims are the printed essentials (event name, date, seat section). Custom claims are handwritten notes the security staff adds: "VIP access," "backstage allowed," or "meet-and-greet approved." These extras help staff make quick decisions without radioing back to the main office.
Design Principles
Keep it minimal: JWTs travel with every authenticated request. A bloated payload means more bandwidth and slower transmission. Only include data you'll actually check on the server.
// ❌ Too much data
{
"sub": "user123",
"email": "user@example.com",
"fullName": "Jane Smith",
"address": "123 Main St...",
"preferences": {...},
"purchaseHistory": [...]
}
// ✅ Lean and purposeful
{
"sub": "user123",
"role": "admin",
"permissions": ["read", "write"]
}
Avoid sensitive data: Remember, JWTs are encoded (not encrypted)—anyone can decode them. Never include passwords, credit card numbers, or private information. Store those server-side and fetch them when needed.
Use clear naming: Custom claims should be descriptive and namespace them if needed (app_role instead of just role) to avoid conflicts with future JWT standards.
Key Takeaway: Custom claims make JWTs powerful by embedding authorization data, but keep payloads small and never include sensitive information—JWTs are visible to anyone holding them.