Complete Guide to JWT Tokens

1. What is a JWT Token?

JWT (JSON Web Token) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed.

JWTs can be signed using a secret (with HMAC algorithm) or a public/private key pair using RSA or ECDSA. While JWTs can also be encrypted to provide secrecy between parties, signed tokens are most commonly used for authentication and information exchange.

2. JWT Structure Explained

A JWT consists of three parts separated by dots (.), which are:

• Header — Contains the token type and signing algorithm
• Payload — Contains the claims (the actual data)
• Signature — Ensures the token hasn't been altered

A typical JWT looks like this:

Each part is Base64URL encoded, making the token URL-safe and compact for transmission in HTTP headers.

3. The JWT Header

The header typically consists of two parts: the type of token (JWT) and the signing algorithm being used.

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

Common header fields include:

• alg — The signing algorithm (HS256, RS256, ES256, etc.)
• typ — The token type, usually "JWT"
• kid — Key ID, used when multiple keys are in rotation

4. The JWT Payload and Claims

The payload contains the claims. Claims are statements about an entity (typically the user) and additional data. There are three types of claims:

Registered Claims

These are predefined claims defined in the JWT specification (RFC 7519):

• iss (Issuer) — Who issued the token
• sub (Subject) — The subject of the token (usually user ID)
• aud (Audience) — The intended recipient of the token
• exp (Expiration Time) — When the token expires (Unix timestamp)
• nbf (Not Before) — When the token becomes valid
• iat (Issued At) — When the token was issued
• jti (JWT ID) — Unique identifier for the token

Public Claims

These can be defined by anyone but should be registered in the IANA JSON Web Token Registry or use collision-resistant names (like URIs).

Private Claims

Custom claims created to share information between parties that agree on using them, such as:

{
  "sub": "1234567890",
  "name": "John Doe",
  "email": "john@example.com",
  "role": "admin",
  "permissions": ["read", "write", "delete"],
  "iat": 1516239022,
  "exp": 1516242622
}

5. The JWT Signature

The signature is used to verify that the sender of the JWT is who it says it is and to ensure that the message wasn't changed along the way. To create the signature, you take:

1. The encoded header
2. The encoded payload
3. A secret (for HMAC) or private key (for RSA/ECDSA)
4. The algorithm specified in the header

For HMAC SHA256, the signature is created like this:

6. JWT Signing Algorithms

JWT supports several signing algorithms, each with different characteristics:

HMAC (Symmetric)

Uses a shared secret for both signing and verification. Both parties must have the same secret.

• HS256 — HMAC with SHA-256
• HS384 — HMAC with SHA-384
• HS512 — HMAC with SHA-512

RSA (Asymmetric)

Uses a private key to sign and a public key to verify. Ideal when multiple parties need to verify tokens.

• RS256 — RSA with SHA-256 (most common)
• RS384 — RSA with SHA-384
• RS512 — RSA with SHA-512

ECDSA (Asymmetric)

Elliptic curve cryptography provides similar security to RSA with smaller keys and faster operations.

• ES256 — ECDSA with P-256 curve
• ES384 — ECDSA with P-384 curve
• ES512 — ECDSA with P-521 curve

Learn more about each algorithm on our JWT Algorithms Explained page.

7. JWT for Authentication

The most common use case for JWT is authentication. Here's how a typical JWT authentication flow works:

1. User logs in with credentials (username/password)
2. Server validates credentials and generates a JWT
3. Server sends the JWT back to the client
4. Client stores the JWT (usually in localStorage or httpOnly cookie)
5. Client sends the JWT with every subsequent request (typically in Authorization header)
6. Server validates the JWT signature and grants access to protected resources

8. JWT Security Best Practices

• Always verify the signature — Never trust a token without verifying its signature first.
• Validate all claims — Check exp, iss, aud, and other claims match expected values.
• Use short expiration times — Access tokens should expire quickly (15 minutes to 1 hour).
• Implement refresh tokens — Use long-lived refresh tokens to obtain new access tokens.
• Store tokens securely — Use httpOnly cookies to prevent XSS attacks.
• Use HTTPS only — Never transmit JWTs over unencrypted connections.
• Keep secrets secure — Never expose HMAC secrets in client-side code.
• Consider token revocation — Implement a blacklist for logout or security breaches.
• Avoid sensitive data in payload — JWTs are encoded, not encrypted.

9. JWT vs Session-Based Authentication

10. Common JWT Mistakes

• Using "none" algorithm — Some libraries accept tokens without signatures. Always enforce algorithm verification.
• Storing sensitive data — Putting passwords, credit cards, or PII in the payload.
• Not validating expiration — Accepting expired tokens is a security risk.
• Weak secrets — Using short or predictable secrets for HMAC signing.
• Exposing tokens in URLs — Tokens in query strings get logged and cached.
• Not using HTTPS — Tokens can be intercepted over unencrypted connections.