What is a JWT?

Pronounced “jot” by the people who wrote the spec and “jay-double-you-tee” by everyone else, a JWT is the token format that quietly powers most modern SaaS authentication. When a user signs in to a Next.js app backed by Supabase, Clerk, or Auth.js, the artifact that gets handed back to the browser and replayed on every API call is almost always a JWT. Understanding what is inside one — and what should never be inside one — is the difference between auth that holds up and auth that quietly leaks.

The structure: header.payload.signature

A JWT looks like a long, mildly garbled string with two dots in it. Decoded, it is three pieces:

Each segment is base64url-encoded (the URL-safe variant of base64, which swaps +/ for -_ and drops padding). When you base64url-decode the first two segments, you get JSON:

The header tells the verifier which algorithm was used to sign the token. The payload contains the claims — standardised fields like sub (subject, almost always the user ID), iat (issued at), exp (expires at), iss (issuer), and aud (audience), plus any custom claims the issuer wants to ship along. The signature is computed over base64url(header) + "." + base64url(payload) using the algorithm in the header and a secret or private key only the issuer holds.

Two important consequences fall out of that structure. First, the payload is not encrypted, only encoded. Anyone holding the token can read the claims by base64url-decoding the middle segment — tools like jwt.io will do it for you. Second, the signature is what makes the token trustworthy. If an attacker tampers with even one byte of the payload, the signature stops verifying, and any well-behaved server rejects the token.

Signed vs encrypted: JWS vs JWE

The umbrella term “JWT” covers two cousins from the JOSE (JavaScript Object Signing and Encryption) family of specs: JWS (JSON Web Signature, RFC 7515) and JWE (JSON Web Encryption, RFC 7516). The signed-only variant — JWS — is overwhelmingly the one you encounter in SaaS auth. The payload is readable by anyone, but the signature guarantees integrity.

Encrypted JWTs (JWEs) wrap an encrypted payload inside a different five-segment structure. They are useful when claims contain genuinely sensitive data, but they are rare in practice for one reason: well-designed JWTs do not contain sensitive data. They contain a user ID and a few flags. If you find yourself reaching for JWE, you have probably stuffed something into the payload that should have stayed in the database.

Signing algorithms you will see

The header's alg field identifies how the signature was made. Three families dominate:

• HS256 (HMAC with SHA-256). Symmetric. The same secret is used to sign and verify, which means every service that verifies tokens has to hold the signing key. Fine for a single backend, awkward as soon as multiple services need to verify.
• RS256 (RSA with SHA-256). Asymmetric. The issuer signs with a private key; verifiers use a public key. This is what almost every hosted auth provider uses, because verifiers can trust signatures without ever holding a secret.
• ES256 (ECDSA on the P-256 curve). Also asymmetric, but with shorter keys and smaller signatures than RS256. Increasingly common in newer issuers.

Auth0's and Clerk's hosted issuers default to RS256. Supabase Auth historically used HS256 with a project-wide secret and has been migrating projects toward asymmetric signing. Whichever family you use, the rule is the same: never accept tokens whose alg is none. The infamous “alg: none” vulnerability from 2015 is still appearing in audit reports a decade later because some libraries trust the header instead of pinning the algorithm in the verifier.

Why SaaS uses JWTs: stateless auth

The whole point of a signed, self-contained token is that the server does not need to store session state. With a session-cookie design, every authenticated request triggers a database lookup — the cookie holds an opaque session ID, and the server reads the row to figure out which user this is. With a JWT, the user ID is already in the token. The server verifies the signature once (using a key it already has cached), reads sub out of the payload, and proceeds.

For solo SaaS founders, that buys three things:

• Horizontal scale without sticky sessions. Any server in any region can verify the token; there is no shared session table to consult.
• Mobile and SPA tokens that work everywhere. A native iOS app, a React Native app, and a Next.js frontend can all hold the same JWT in their respective storage layers and replay it against any backend.
• Cross-service identity in a microservice setup. Service B trusts a token signed by the auth issuer without calling service A. This is how Supabase's Postgres can let an end user's JWT drive RLS policies — the database verifies the signature directly. We dig into that pattern in how row level security actually works.

Access tokens vs refresh tokens

Real-world JWT setups almost always issue two tokens at sign-in:

• Access token. Short-lived (5–60 minutes). Sent on every API request. Carries the claims your backend needs (user ID, roles, organization ID). When it expires, the user is no longer authenticated for new requests.
• Refresh token. Long-lived (days to months). Held privately by the client and never sent to your normal API. Its only job is to ask the auth endpoint for a fresh access token without forcing the user to log in again.

The split exists because long-lived JWTs are dangerous — once issued, you cannot easily revoke them — and short-lived JWTs without a refresh would log users out every fifteen minutes. The refresh token is typically opaque (not a JWT), stored in a secure HTTP-only cookie, and tied to a server-side record so it can be revoked. Auth0's, Clerk's, and Supabase Auth's docs all describe variations of this pattern.

Common JWT mistakes

• Storing access tokens in localStorage. XSS vulnerabilities become full account takeover, because any script on the page can read the token and exfiltrate it. OWASP's guidance is to keep tokens in HTTP-only, Secure, SameSite cookies whenever possible. SPAs that can't use cookies for cross-origin reasons should at least keep the access token in memory and rely on a cookie-based refresh flow.
• Not validating the signature. Every production JWT library has a verify function and a decode function. Never use decode for auth checks — it parses the payload but skips the signature. Always verify, always pin the expected algorithm, and always check iss and aud against your own values.
• Skipping expiry checks. A JWT without an exp claim is a credential that lives forever. Issue tokens with short expiries, reject expired ones, and rotate refresh tokens.
• Putting sensitive data in the payload. Email is borderline; phone number, billing data, anything PII-grade is a leak waiting to happen. The payload is base64url-encoded plaintext — treat it as public.
• Trusting the alg field from the token. Hard-code the expected algorithm in your verifier. Otherwise an attacker can switch RS256 for HS256 and trick a buggy library into using the public key as the HMAC secret.
• Forgetting that JWTs cannot be revoked easily. If a user changes their password, their old access token is still valid until it expires. For sensitive applications, keep a server-side allowlist of token IDs (jti) or use very short expiries.

JWT vs session cookies (the never-ending debate)

You will read a lot of takes online claiming JWTs are an anti-pattern and you should use session cookies instead. The pragmatic answer is more boring than either side admits: they are not actually opposites. Most modern auth providers issue a JWT inside an HTTP-only cookie, getting the integrity properties of a signed token and the storage properties of a cookie at the same time.

The practical guidance: use whichever format your auth provider issues by default, store it in an HTTP-only cookie if same-origin, and don't over-engineer. The interesting security questions are about token lifetime and refresh handling, not about the token format.

Tools that issue JWTs for solo SaaS

You almost certainly should not write your own JWT issuer. The hosted and open-source options that handle this for solo founders are mature and cheap or free at small scale:

• Supabase Auth. Issues JWTs that double as the auth context for Postgres RLS. The same token authenticates your API and filters database rows in magic-link flows.
• Clerk. Hosted auth with pre-built React components. Issues short-lived JWTs and handles refresh transparently. Custom JWT templates let you mint Supabase-compatible tokens. Compared in Clerk vs Supabase Auth.
• Auth.js (formerly NextAuth). Open-source, runs inside your Next.js app, can issue JWT-shaped sessions or database sessions. Covered in best auth library for Next.js.
• Better Auth. Newer open-source library aiming to fix Auth.js's rough edges. Issues JWTs and supports more providers out of the box.

How Supabase RLS uses the JWT

The JWT’s killer use case in the Supabase stack is that Postgres itself reads the token. When a request hits PostgREST with an Authorization: Bearer <jwt> header, the gateway verifies the signature, then sets a Postgres session variable containing the decoded claims. RLS policies on tables can then reference auth.uid() — a SQL function that pulls sub out of the JWT — to filter rows. The result: a single signed token, issued at sign-in, drives every authorisation decision from the API edge down to the row level. We walk through the wiring in what is RLS and the multi-tenant patterns in what is multi-tenancy. JWTs also show up alongside other integration primitives like webhooks, where they often sign the webhook payload to prove the sender.

The takeaway

A JWT is three base64url-encoded segments with a signature on the end. It carries a user’s identity in a way any service holding the verification key can trust without a database lookup. For solo SaaS, that property — stateless, cross-service identity — is what makes the token format worth using. The mistakes are well-known and avoidable: keep tokens out of localStorage, pin algorithms in your verifier, give every token an expiry, and never put PII in the payload. Get those four right and the format does its job quietly for the entire life of your product.