What are JWT claims and how do I use them?

JWT claims are the pieces of information asserted about a subject in the token payload.

Standard Claims (Registered):

These have predefined meanings in the JWT specification:

• iss (Issuer): Who created and signed 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)
• nbf (Not Before): Token not valid before this time
• iat (Issued At): When the token was created
• jti (JWT ID): Unique identifier for the token

Custom Claims (Private):

You can add any custom data you need:

{
  "userId": "12345",
  "email": "user@example.com",
  "role": "admin",
  "permissions": ["read", "write", "delete"]
}

{
  "userId": "12345",
  "email": "user@example.com",
  "role": "admin",
  "permissions": ["read", "write", "delete"]
}

Best Practices:

1. Keep it small: JWTs are sent with every request
2. Don't include secrets: Tokens can be decoded by anyone
3. Use standard claims: They're widely understood and validated
4. Include expiration: Always set exp to limit token lifetime
5. Be consistent: Use the same claim names across your application

Reading Claims:

After decoding a JWT, you can read claims to:

• Check if the token is expired (exp < current time)
• Verify the token is for your application (aud matches)
• Extract user information (sub, custom claims)
• Implement role-based access control (role, permissions)

Common Mistakes:

• Storing sensitive data in claims (they're not encrypted!)
• Not validating standard claims like exp and aud
• Making tokens too large with unnecessary data
• Not using appropriate data types (use Unix timestamps for dates)

Claims are the core of JWT's usefulness, allowing stateless authentication while carrying necessary user context.