DEV Community

Safal Bhandari
Safal Bhandari

Posted on

🛡️ JWT Industry Conventions: Best Practices and Standards for Secure Token Design

#security #backend #webdev #architecture

JSON Web Tokens (JWTs) have become the industry standard for stateless authentication in modern web applications. They’re compact, secure (when used properly), and easy to transmit between clients and servers. But to ensure consistency, interoperability, and security, it’s important to follow the established conventions when designing and implementing JWTs.

This article explores the key conventions, standard claims, and best practices used across the industry for JWT-based authentication systems.

🔍 What is a JWT?

A JSON Web Token is a compact, URL-safe string that represents a set of claims about an entity — usually a user. It has three parts:

xxxxx.yyyyy.zzzzz
Enter fullscreen mode Exit fullscreen mode
  1. Header – Metadata about the token (e.g., signing algorithm)
  2. Payload – The claims (e.g., user ID, roles, expiration)
  3. Signature – A cryptographic signature verifying integrity

Example header and payload:

// Header
{
  "alg": "HS256",
  "typ": "JWT"
}

// Payload
{
  "sub": "user_12345",
  "iat": 1730300000,
  "exp": 1732900000,
  "role": "admin"
}
Enter fullscreen mode Exit fullscreen mode

🧩 Standard JWT Claims

The JWT specification (RFC 7519) defines several registered claim names that carry specific meanings. Using these consistently ensures your tokens are compatible with libraries, identity providers, and standard middleware.

Claim Meaning Example Notes
sub Subject — the unique identifier for the entity the token represents "sub": "user_12345" Industry convention is to store the user ID here
iss Issuer — who issued the token "iss": "myapp.com" Helps verify token origin
aud Audience — who the token is intended for "aud": "myapp-api" Used for multi-service validation
exp Expiration Time "exp": 1732900000 Prevents token reuse after expiration
iat Issued At "iat": 1730300000" When the token was created
nbf Not Before "nbf": 1730300000" Token isn’t valid until this time

💡 Why use sub for user IDs?

sub (short for subject) is the standard way to identify the token’s owner.
For example:

jwt.sign({ sub: user.id, role: 'user' }, secret, { expiresIn: '15m' });
Enter fullscreen mode Exit fullscreen mode

Using sub instead of a custom userId claim ensures your tokens:

  • Comply with the JWT standard
  • Work smoothly with common tools like Passport.js, Auth0, Cognito, and Firebase
  • Are easier to understand and maintain

🛠️ Access Tokens vs Refresh Tokens

JWTs are often used in access/refresh token pairs:

Type Lifetime Purpose Example Claims
Access Token Short (e.g., 15 minutes) Grants access to protected resources sub, iat, exp, role
Refresh Token Long (e.g., 30 days) Allows obtaining new access tokens sub, tokenId, iat, exp

Typical structure for a refresh token payload:

{
  "sub": "user_12345",
  "tokenId": "f5d9a0c7-32b4-4c3a-9a56-7c8b1e98e8de",
  "iat": 1730300000,
  "exp": 1735500000
}
Enter fullscreen mode Exit fullscreen mode

Including a unique tokenId allows you to revoke or rotate refresh tokens individually in your database.

🔐 Security Best Practices

  1. Use strong signing algorithms — Prefer HS256 or RS256 (asymmetric keys for better isolation).
  2. Never store sensitive data in the JWT — It’s only base64-encoded, not encrypted.
  3. Set short expiration times (exp) — Especially for access tokens.
  4. Rotate refresh tokens — Invalidate old tokens when new ones are issued.
  5. Use HTTPS — Always transmit tokens securely.
  6. Validate issuer and audience — Prevent cross-application misuse.
  7. Blacklist or revoke tokens when users log out or credentials are compromised.

🧱 Example JWT Workflow

  1. User logs in → Server issues an access + refresh token
  2. Access token expires → Client uses refresh token to get a new one
  3. Refresh token is rotated → Old one revoked, new one stored
  4. Server validates sub → Uses it to identify the correct user

✅ Conclusion

Following JWT conventions isn’t just about style — it’s about security, interoperability, and maintainability.
Using standard claims like sub, iss, and exp ensures your tokens work seamlessly across services and tools, while applying strong security practices keeps your authentication layer robust.

By designing tokens that align with industry norms and the JWT specification (RFC 7519), your authentication system will be both future-proof and secure.

Top comments (0)