Security2026-08-237 min readClient-Side Engine

JWT Structure & Claims: Anatomy of a JSON Web Token (RFC 7519)

Deep dive into JSON Web Token (JWT) architecture: RFC 7519 structure, registered vs custom claims, Base64URL encoding, and signature verification mechanics.

CoShareXCore Engineering Team

Anatomy of a JWT: Three Dot-Separated Segments

A JSON Web Token (RFC 7519) is a compact, URL-safe string consisting of three distinct segments separated by periods (.): Header, Payload, and Signature (header.payload.signature):

Header: Contains token metadata and cryptographic algorithm specification (e.g. {"alg": "HS256", "typ": "JWT"}).
Payload: Contains claims—statements about an entity (typically the authenticated user) and security context metadata.
Signature: Cryptographic digest generated by hashing Base64URL(Header) + "." + Base64URL(Payload) with a secret key or private key, guaranteeing data integrity.

Registered Claims Reference Table (RFC 7519)

Claim	Full Name	Type	Description & Verification Rule
`iss`	Issuer	String	Identifies the identity provider that issued the JWT (e.g. `https://auth.cosharex.com`).
`sub`	Subject	String	Unique identifier of the principal (user ID or client ID).
`aud`	Audience	String / Array	Identifies the intended recipients (APIs). Token MUST be rejected if audience does not match.
`exp`	Expiration Time	NumericDate (Seconds)	Unix timestamp after which token is expired. Enforce strict rejection.
`nbf`	Not Before	NumericDate (Seconds)	Unix timestamp before which token must not be accepted.
`iat`	Issued At	NumericDate (Seconds)	Unix timestamp when token was generated.
`jti`	JWT ID	String (UUID)	Unique identifier for token; used to enforce one-time usage and blacklist revocation.

Public vs Private Custom Claims

Beyond registered claims, JWT payloads contain custom application data:

json

{
  "iss": "https://auth.cosharex.com",
  "sub": "usr_998124a",
  "aud": "https://api.cosharex.com",
  "exp": 1788931200,
  "iat": 1788927600,
  "jti": "550e8400-e29b-41d4-a716-446655440000",
  
  // Custom Application Claims:
  "role": "workspace_admin",
  "tenant_id": "org_coshare_prime",
  "permissions": ["files:read", "files:write", "paste:create"]
}

Signature Verification Mechanics

Verifying a JWT signature requires reconstructing the signing input from the raw token headers and verifying the digest with the server public/secret key:

typescript

import crypto from 'node:crypto';

export function verifyJwtHmacSha256(token: string, secret: string): boolean {
  const parts = token.split('.');
  if (parts.length !== 3) return false;
  
  const [headerB64, payloadB64, signatureB64] = parts;
  const signingInput = `${headerB64}.${payloadB64}`;
  
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signingInput)
    .digest('base64url');
    
  return crypto.timingSafeEqual(
    Buffer.from(signatureB64),
    Buffer.from(expectedSignature)
  );
}

Critical JWT Security Pitfalls

The "alg": "none" Attack: Always explicitly restrict allowed verification algorithms on backend servers; never rely blindly on the client-supplied header alg.
Storing Sensitive Data in Payload: JWT payloads are Base64URL-encoded, NOT encrypted. Never place passwords, credit cards, or PII in a JWT.
Excessive Expiration Times: Access tokens should have short lifetimes (5-15 minutes), paired with secure HttpOnly refresh token rotation.

Suggested Browser Tool

Code Formatter & Converter Suite

Validate, format, minify, and convert JSON, SQL, YAML, XML, and code dialects directly on your local machine.

Open Formatter App

Frequently Asked Questions

What is the difference between Base64 and Base64URL in JWTs?

Base64URL replaces `+` with `-` and `/` with `_`, and strips all trailing `=` padding characters so that JWT strings can be safely passed in HTTP headers and query strings without percent-encoding.

How can a JWT be revoked before its expiration time?

Revocation is achieved by checking the token `jti` (JWT ID) against a distributed cache (like Redis) or incrementing a `token_version` counter in the user database record.

Conclusion

JSON Web Tokens provide decentralized authorization assertions when properly signed, validated for expiration and audience, and transported via secure channels.

PreviousJSON vs XML: Structural Architecture, Parsing Performance, and Modern Use Cases

NextQR Code Error Correction Levels Explained (L, M, Q, H): Reed-Solomon Math and Logo Embedding

Security

Hashing vs Encryption: Key Differences, Mathematical Foundations, and When to Use Each

Understand the critical differences between one-way cryptographic hashing and two-way reversible encryption, including salt, IVs, and algorithm selection.

Security

How to Decode and Inspect JSON Web Tokens (JWT): Structure, Base64URL, and Security Traps

A security-focused developer guide on decoding JWTs client-side and server-side, parsing JOSE headers and payload claims, handling multi-byte UTF-8 strings, and avoiding verification anti-patterns.

Converters

What is Base64? Binary-to-Text Encoding Explained from Bitwise Roots

A deep architectural guide to Base64 encoding: 6-bit binary chunking, ASCII translation tables, padding mathematics, and URL-safe variants.

Anatomy of a JWT: Three Dot-Separated Segments

A JSON Web Token (RFC 7519) is a compact, URL-safe string consisting of three distinct segments separated by periods (.): Header, Payload, and Signature (header.payload.signature):

Header: Contains token metadata and cryptographic algorithm specification (e.g. {"alg": "HS256", "typ": "JWT"}).

Payload: Contains claims—statements about an entity (typically the authenticated user) and security context metadata.

Signature: Cryptographic digest generated by hashing Base64URL(Header) + "." + Base64URL(Payload) with a secret key or private key, guaranteeing data integrity.

Registered Claims Reference Table (RFC 7519)

Claim	Full Name	Type	Description & Verification Rule
`iss`	Issuer	String	Identifies the identity provider that issued the JWT (e.g. `https://auth.cosharex.com`).
`sub`	Subject	String	Unique identifier of the principal (user ID or client ID).
`aud`	Audience	String / Array	Identifies the intended recipients (APIs). Token MUST be rejected if audience does not match.
`exp`	Expiration Time	NumericDate (Seconds)	Unix timestamp after which token is expired. Enforce strict rejection.
`nbf`	Not Before	NumericDate (Seconds)	Unix timestamp before which token must not be accepted.
`iat`	Issued At	NumericDate (Seconds)	Unix timestamp when token was generated.
`jti`	JWT ID	String (UUID)	Unique identifier for token; used to enforce one-time usage and blacklist revocation.

Public vs Private Custom Claims

Beyond registered claims, JWT payloads contain custom application data:

json

{
  "iss": "https://auth.cosharex.com",
  "sub": "usr_998124a",
  "aud": "https://api.cosharex.com",
  "exp": 1788931200,
  "iat": 1788927600,
  "jti": "550e8400-e29b-41d4-a716-446655440000",
  
  // Custom Application Claims:
  "role": "workspace_admin",
  "tenant_id": "org_coshare_prime",
  "permissions": ["files:read", "files:write", "paste:create"]
}

Signature Verification Mechanics

Verifying a JWT signature requires reconstructing the signing input from the raw token headers and verifying the digest with the server public/secret key:

typescript

import crypto from 'node:crypto';

export function verifyJwtHmacSha256(token: string, secret: string): boolean {
  const parts = token.split('.');
  if (parts.length !== 3) return false;
  
  const [headerB64, payloadB64, signatureB64] = parts;
  const signingInput = `${headerB64}.${payloadB64}`;
  
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signingInput)
    .digest('base64url');
    
  return crypto.timingSafeEqual(
    Buffer.from(signatureB64),
    Buffer.from(expectedSignature)
  );
}

Critical JWT Security Pitfalls

The "alg": "none" Attack: Always explicitly restrict allowed verification algorithms on backend servers; never rely blindly on the client-supplied header alg.

Storing Sensitive Data in Payload: JWT payloads are Base64URL-encoded, NOT encrypted. Never place passwords, credit cards, or PII in a JWT.

Excessive Expiration Times: Access tokens should have short lifetimes (5-15 minutes), paired with secure HttpOnly refresh token rotation.

JWT Structure & Claims: Anatomy of a JSON Web Token (RFC 7519)

Anatomy of a JWT: Three Dot-Separated Segments

Registered Claims Reference Table (RFC 7519)

Public vs Private Custom Claims

Signature Verification Mechanics

Critical JWT Security Pitfalls

Code Formatter & Converter Suite

Frequently Asked Questions

What is the difference between Base64 and Base64URL in JWTs?

How can a JWT be revoked before its expiration time?

Conclusion

Related Articles

Hashing vs Encryption: Key Differences, Mathematical Foundations, and When to Use Each

How to Decode and Inspect JSON Web Tokens (JWT): Structure, Base64URL, and Security Traps

What is Base64? Binary-to-Text Encoding Explained from Bitwise Roots

Ready for faster, account-free developer tools?

JWT Structure & Claims: Anatomy of a JSON Web Token (RFC 7519)

Anatomy of a JWT: Three Dot-Separated Segments

Registered Claims Reference Table (RFC 7519)

Public vs Private Custom Claims

Signature Verification Mechanics

Critical JWT Security Pitfalls

Code Formatter & Converter Suite

Frequently Asked Questions

What is the difference between Base64 and Base64URL in JWTs?

How can a JWT be revoked before its expiration time?

Conclusion

Related Articles

Hashing vs Encryption: Key Differences, Mathematical Foundations, and When to Use Each

How to Decode and Inspect JSON Web Tokens (JWT): Structure, Base64URL, and Security Traps

What is Base64? Binary-to-Text Encoding Explained from Bitwise Roots

Ready for faster, account-free developer tools?