JWT Claims for Authorization

JSON Web Tokens (JWTs) include a claims section — a JSON payload with arbitrary key-value data about the authenticated subject. Authorization systems often use custom JWT claims to carry context that influences access decisions.

Common claims for authorization

{
  "sub": "user-abc123",          // Standard: subject (user ID)
  "email": "alice@acme.com",     // Standard: email
  "orgId": "acme-corp",          // Custom: organization ID
  "scopeId": "workspace-prod",   // Custom: active workspace/scope
  "roles": ["admin"],            // Custom: pre-computed role list (use with care)
  "plan": "business"             // Custom: subscription tier
}

JWT claims vs. dynamic authorization

Embedding roles or permissions directly in JWT claims is tempting (no API call needed to check access), but has significant drawbacks:

• Staleness: JWTs are issued at login and valid until expiry. If a user's role changes, they keep the old permissions until their token expires.
• Revocation: You can't revoke individual claims from an issued JWT.
• Trust boundary: The authorization decision happens client-side (in JWT verification), not in a controlled server-side system.

For security-sensitive applications, use JWT claims only to carry identity (sub,orgId, scopeId) and make the authorization decision via a dedicated API call like EC WardenAuth's POST /v1/has-access.

In WardenAuth

WardenAuth uses your authentication provider (Cognito, Auth0, etc.) for identity. The subjectId you pass to access checks is typically the subclaim from the user's JWT. The scopeId comes from the active workspace context, not the JWT — this prevents users from impersonating other tenants.