Course contentsShow
← Web Development
Lesson 1582 of 2,98229. Web Authentication PatternsFree lesson

Custom Claims and Payload Design

Adding custom claims to JWTs while keeping payload size minimal and avoiding sensitive data.

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.