← Back to blog

What Is a JWT? A Practical Guide to JSON Web Tokens

JWTs are one of those technologies that almost everyone uses and many people only partly understand. You see them in API docs, OAuth flows, mobile backends, and service-to-service auth, but the explanations are often either too shallow or too academic.

This post is the practical middle ground. The goal is to answer five core questions clearly:

  1. What is a JWT?
  2. What does it stand for, and why?
  3. What did JWT replace?
  4. How are JWTs used in modern environments?
  5. How are JWTs secure, and are they encrypted?

If you understand these five points, you can design better authentication and authorization systems and avoid the common mistakes that cause real production incidents.

What Is a JWT?

A JWT is a compact token format used to carry claims between systems. A claim is just a statement about something, usually a user or a client app. Common claims include a user ID, issuer, expiration time, and permissions.

JWTs are most often used as access tokens. After a user signs in, an auth server issues a JWT. The client sends that token with requests, and APIs validate it before granting access.

A JWT has three parts separated by dots:

header.payload.signature

Each part is Base64URL-encoded text:

  1. header: metadata such as token type and signing algorithm.
  2. payload: claims such as sub (subject), iss (issuer), aud (audience), exp (expiration), and custom app claims.
  3. signature: cryptographic proof that header and payload were issued by a trusted signer and were not modified.

So at a high level, a JWT is not magic. It is a signed data container optimized for transport across web systems.

What Does JWT Stand For, and Why?

JWT stands for JSON Web Token.

Each word matters:

  1. JSON: claims are represented as JSON key-value pairs.
  2. Web: designed for web transport, especially HTTP headers.
  3. Token: a portable credential that can represent identity and authorization context.

The standard was designed to be compact and interoperable. Compact means it fits well in HTTP headers. Interoperable means different systems, languages, and frameworks can issue and validate it consistently.

That design goal matters in distributed systems. If one component is written in Node.js, another in Go, and another in Java, they can still share identity context through a standard token format instead of inventing custom session plumbing for each boundary.

What Did JWT Replace?

JWT did not "replace" everything, but it became popular because it solves pain points from older session-centric architectures.

The Older Session Model

In the classic server-rendered monolith model:

  1. User logs in with credentials.
  2. Server creates a session record in server-side storage (memory, DB, Redis).
  3. Client gets a session ID in a cookie.
  4. On every request, server looks up session state by session ID.

This works well in many monoliths. But scaling it across many services and trust domains gets complicated.

Why Session IDs Became Painful in Distributed Systems

Session systems rely on a shared server-side state store. As architecture becomes more distributed, this creates issues:

  1. Every service that needs auth context must call or trust the central session store.
  2. Cross-region and multi-cluster deployments add latency and consistency concerns.
  3. Integrating third-party systems is harder because sharing direct session infrastructure is risky.
  4. API-first and mobile ecosystems prefer explicit bearer credentials over implicit cookie/session coupling.

JWTs reduce that coupling by carrying validated claims in the token itself. Services can verify the token signature locally (or via cached keys) without querying a session store on every call.

Important nuance: session-based auth is still valid and often best for simpler apps. JWTs are not automatically superior. They are better for specific architecture needs, especially distributed APIs and delegated trust across services.

How JWTs Actually Work

To use JWTs correctly, it helps to understand the flow at a protocol level, not just framework helpers.

Issuance

  1. User authenticates with an identity provider or auth server.
  2. Server evaluates credentials and policy (MFA, account state, risk checks).
  3. Server creates claims and signs a JWT.
  4. Client receives the JWT (usually as an access token).

Verification

When an API receives a bearer JWT, it should validate:

  1. Signature is cryptographically valid.
  2. exp has not passed.
  3. nbf (if present) is satisfied.
  4. iss matches the trusted issuer.
  5. aud matches the current API.
  6. Any app-specific claims required for the route are present.

Only then should authorization logic proceed.

The Trust Model

JWT systems are fundamentally about trust delegation. APIs trust the issuer. If the issuer signs the token and claims pass validation, downstream services accept that identity context.

That lets teams separate concerns cleanly:

  1. Auth server specializes in authentication and token issuance.
  2. Resource APIs specialize in business authorization based on validated claims.

This pattern is a core reason JWTs are common in microservices and API platforms.

JWT in Modern Environments

JWT usage today is broader than just "user login token in a SPA." Here are common production patterns.

OAuth 2.0 and OpenID Connect

In modern identity systems, JWTs often appear as:

  1. Access tokens: presented to APIs for authorization.
  2. ID tokens (OIDC): presented to clients with identity information about the authenticated user.

Not every access token must be JWT, but JWT-formatted access tokens are common because resource servers can validate them efficiently.

Microservices and API Gateways

A typical architecture:

  1. Client authenticates once.
  2. Gateway validates token at the edge.
  3. Internal services either re-validate or trust forwarded identity context.

This avoids centralized per-request session lookups and supports high-throughput stateless request handling.

Mobile and Single-Page Applications

SPAs and mobile apps often use short-lived JWT access tokens plus longer-lived refresh tokens:

  1. Access token expires quickly (for example, 5-15 minutes).
  2. Refresh token is exchanged for new access tokens.
  3. Refresh token rotation reduces replay risk if stolen.

The short lifetime limits blast radius when an access token leaks.

Machine-to-Machine Auth

Service accounts and backend jobs also use JWT flows. A client credential flow may issue a token representing an application identity rather than a human user.

Claims then encode app scopes, tenant boundaries, or service permissions.

Multi-Tenant SaaS

JWT claims often carry tenant context (org_id, tenant role, entitlement flags). This helps enforce tenant-aware authorization across services without repeated identity database calls.

But claims design must stay minimal and stable. Cramming too much mutable business state into tokens creates staleness and security drift.

Statelessness: Strength and Tradeoff

People call JWTs "stateless." That is mostly true for access token validation: APIs can validate locally using signature and claims.

The benefit is scalability and decoupling.

The tradeoff is control. If you issue a long-lived token and then user privileges change, that token may remain valid until expiration unless you add revocation controls.

That is why serious systems pair JWT access tokens with:

  1. Short expiry windows.
  2. Refresh token policies.
  3. Revocation mechanisms for high-risk events.

Stateless does not mean "no state anywhere." It means you do not need per-request session lookups for every protected API call.

How Are JWTs Secure?

JWT security comes from digital signatures and strict validation, not from secrecy of payload text.

Signature Integrity

If an attacker changes payload claims (for example, role: user to role: admin), signature verification fails unless the attacker can sign with the issuer's secret/private key.

That is the core protection:

  1. Integrity: data was not altered after issuance.
  2. Authenticity: token was issued by trusted signer.

Symmetric vs Asymmetric Signing

Common signing options:

  1. HMAC (for example HS256): issuer and verifier share one secret.
  2. RSA/ECDSA (for example RS256, ES256): issuer signs with private key; verifiers validate with public key.

Asymmetric signing is common in distributed systems because many services can verify with public keys while only issuer holds the private key.

Key Distribution and Rotation

Production systems publish public keys via metadata/JWKS endpoints. Verifiers fetch and cache keys, and key IDs (kid) help select the right key.

Secure operations require:

  1. Planned key rotation.
  2. Safe cache invalidation.
  3. Monitoring verification failures.
  4. Fast response for key compromise events.

Claim Validation Discipline

Many JWT breaches are not broken crypto; they are broken validation logic.

Frequent mistakes:

  1. Accepting tokens without checking aud or iss.
  2. Ignoring expiration or clock skew edge cases.
  3. Trusting unvalidated custom claims for privileged actions.
  4. Allowing weak or unexpected algorithms.

Security depends on complete validation, not just "library says token parsed."

Are JWTs Encrypted?

This is one of the biggest misconceptions.

Most JWTs you see in apps are signed, not encrypted.

Base64URL encoding is not encryption. Anyone who gets the token can decode header and payload and read claims. They cannot forge a valid signature, but they can see claim contents.

So:

  1. JWT payloads are often readable by whoever possesses the token.
  2. Never put secrets or sensitive personal data in plaintext claims.
  3. Use HTTPS everywhere to protect token transport.

JWS vs JWE

Technically:

  1. JWS (JSON Web Signature): signed token, integrity/authenticity.
  2. JWE (JSON Web Encryption): encrypted token, confidentiality.

Most application JWT usage is JWS. JWE is used when claim confidentiality is also required. It adds complexity, so teams use it selectively.

If you need confidentiality, evaluate whether encrypted tokens are necessary or whether opaque reference tokens plus backend lookup are simpler and safer.

What JWT Did Not Replace

JWTs did not eliminate:

  1. Authorization checks in your app logic.
  2. Need for secure transport and storage.
  3. Need for threat modeling.
  4. Need for session concepts (refresh workflows still maintain state somewhere).

Also, JWTs did not make logout trivial. You cannot instantly invalidate all previously issued stateless access tokens unless they are short-lived or backed by active revocation controls.

Token Lifetimes, Refresh, and Rotation

A mature setup usually separates token responsibilities:

  1. Short-lived access JWTs for APIs.
  2. Longer-lived refresh tokens stored and managed securely server-side.

When access tokens expire, client uses refresh token to obtain a new one.

Good practice:

  1. Keep access tokens short-lived.
  2. Rotate refresh tokens on each use.
  3. Detect refresh token reuse (possible theft signal).
  4. Bind refresh tokens to session/device context when possible.
  5. Revoke refresh tokens on logout/password reset/high-risk events.

This pattern significantly reduces exposure from token theft while preserving good user experience.

Storage and Client-Side Risk

Bearer tokens are like cash: possession is enough to spend them.

So token storage matters:

  1. localStorage is vulnerable to XSS exfiltration.
  2. Cookies can be safer when HttpOnly, Secure, and SameSite are configured correctly.
  3. CSRF and XSS risks must be balanced based on architecture.

There is no one universal answer, but there is one universal principle: defend the browser runtime aggressively and minimize token lifetime and scope.

Common JWT Anti-Patterns

These are frequent real-world failures:

  1. Long-lived access tokens with broad scopes.
  2. Putting PII or secrets in payload claims.
  3. Skipping aud and iss checks.
  4. Accepting tokens from multiple issuers without strict routing rules.
  5. Rolling custom crypto instead of vetted libraries.
  6. Using JWT for destructive operations without step-up verification.

For sensitive actions (password changes, account closure, high-value transfers), require stronger checks such as re-authentication, recent MFA, or transaction signing.

When Not to Use JWT

JWT is not mandatory. Consider alternatives when:

  1. Your app is a simple monolith and server sessions solve the problem cleanly.
  2. You need immediate revocation guarantees for every request.
  3. You prefer opaque tokens with introspection for centralized control.
  4. You do not need cross-service delegated trust.

Architecture decisions should be driven by constraints, not trends.

A Mental Model That Works

Use this framing:

  1. Authentication proves who the principal is.
  2. JWT transports signed claims about that principal.
  3. Authorization decides what the principal can do right now.

JWT helps with step 2. It does not replace steps 1 or 3.

That mental model prevents most misuse.

Final Answer to the Five Questions

  1. What is a JWT?
    It is a compact, signed token format carrying claims, typically used as an access token in web APIs.

  2. What does it stand for, and why?
    JSON Web Token. JSON for claim structure, Web for transport context, Token for portable credential; designed for compact interoperability.

  3. What did JWT replace?
    In many distributed systems, it reduced reliance on centralized server sessions and session-ID lookups for every request. It did not eliminate all session/state patterns.

  4. How are JWTs used in modern environments?
    OAuth/OIDC flows, API gateways, microservices, SPA/mobile backends, and machine-to-machine authorization, usually with short-lived access tokens and refresh workflows.

  5. How are JWTs secure? Are they encrypted?
    Security comes from signature verification plus strict claim validation. Most JWTs are not encrypted; they are encoded and signed. Use JWE if confidentiality is required.

JWTs are powerful when used with discipline: minimal claims, short lifetimes, strict validation, safe key management, and realistic threat modeling. Without that discipline, they are just portable risk.