Header & Payload Best Practices

JWT Header & Payload Best Practices

Header Guidelines

Required Fields

Always include alg in the header — it specifies the signing algorithm used.

Common Header Parameters

• typ: Typically "JWT". Optional but recommended.
• kid: Key ID — hints which key was used. Essential when rotating keys.
• cty: Content type — rarely used, only for nested JWTs.

Security-Critical Rules

1. Never accept "none" algorithm in production — always validate the algorithm matches what you expect
2. Validate the typ if your application handles multiple token types
3. Use kid properly — ensure it maps to a known, valid key

Payload Best Practices

Registered Claim Names

Use these standard claims for interoperability:

• iss (Issuer) — Case-sensitive string or URI identifying the principal that issued the JWT
• sub (Subject) — Identifies the subject of the JWT (usually a user ID)
• aud (Audience) — Recipient(s) the JWT is intended for
• exp (Expiration Time) — Unix timestamp after which the JWT must not be accepted
• nbf (Not Before) — Unix timestamp before which the JWT must not be accepted
• iat (Issued At) — Unix timestamp when the JWT was issued
• jti (JWT ID) — Unique identifier; prevents replay attacks

Custom Claims

Use namespaced names to avoid collisions:

{
  "https://api.example.com/roles": ["admin", "editor"]
}

Common Mistakes to Avoid

1. Storing sensitive data — JWTs are signed, not encrypted. Anyone with the token can read the payload
2. Missing expiration — Always set exp to limit token lifetime
3. Oversized payloads — Large payloads increase token size and bandwidth usage
4. Using iat without exp — Issued-at alone doesn't limit token validity