Coder Legion - Recent posts tagged sessions

What Is Authentication? A Beginner's Guide (2026)

Tue, 01 Sep 2026 05:07:56 +0000

Every time you type your email and password into a login form, something is quietly deciding whether you actually get in. That decision — proving you are who you say you are — is called authentication, and it's one of those concepts every developer touches constantly but rarely stops to explain from scratch.

If you've ever wondered what actually happens between "click Sign In" and "welcome back," or mixed up authentication with authorization in an interview, this guide is for you. By the end, you'll know exactly what authentication is, how the major methods work under the hood, and how to build a basic authentication flow yourself.

What Is Authentication? (Quick Answer)

Authentication is the process of verifying that someone is who they claim to be. It answers one question: "Who are you?" This usually happens by checking a password, a code from your phone, a fingerprint, or a token — something only the real user should have or know.

Authentication is different from authorization, which answers a separate question: "What are you allowed to do?" A logged-in user is authenticated. Whether that user can delete another person's account is authorization. Mixing these two up is one of the most common beginner mistakes — keep them mentally separate from the start.

💡 Simple way to remember it: Authentication = ID check at the door. Authorization = the guest list that decides which rooms you can enter once you're inside.

Why Authentication Matters

Without proper authentication and authorization, an app that stores personal data could expose private information to unauthorized users. Authentication provides the identity context that many authorization, personalization, and auditing systems rely on.

It matters for a few concrete reasons:

Privacy — only the right person sees their own data
Security — prevents account takeover and unauthorized access
Personalization — apps can remember who you are across visits
Accountability — actions can be traced back to a real identity (important for admin tools, financial apps, audit logs)

Authentication vs. Authorization: The Difference That Trips Everyone Up

	Authentication	Authorization
Question it answers	Who are you?	What can you do?
Happens	First	After authentication
Example	Logging in with a password	Only admins can access `/admin`
Failure result	401 Unauthorized	403 Forbidden

Why the HTTP status codes are confusingly named: 401 Unauthorized actually means "you're not authenticated" (log in first), while 403 Forbidden means "you're authenticated, but not allowed to do this." Yes, 401 should really be called "Unauthenticated" — it's a long-standing naming quirk in the HTTP spec that trips up almost every developer at least once.

Related: Role-Based Access Control (RBAC) in Next.js 16 goes deep on the authorization half of this once you're ready for it.

How Authentication Works (Step by Step)

At a high level, almost every authentication system follows the same basic loop:

The user provides credentials — a password, a fingerprint, a one-time code, or an existing account from another provider (like signing in with Google)
The server verifies those credentials — checking a hashed password, validating a signed token, or confirming a biometric match
The server issues proof of identity — usually a session or a token, stored in a cookie or sent back to the client
That proof is sent with future requests — so the user doesn't have to log in again on every page

User submits credentials
        ↓
Server verifies credentials
        ↓
Server issues session/token
        ↓
Client stores it (cookie)
        ↓
Future requests include it
        ↓
Server verifies it's still valid

That last step — verifying the proof of identity on every request — is what keeps a user "logged in" without asking for their password on every single page.

The Main Types of Authentication

There isn't just one way to authenticate someone. Here are the methods you'll actually run into as a developer.

1. Password-Based Authentication

The classic: a username/email plus a password, checked against a hashed value stored in your database. Never store plain-text passwords — always hash them with a slow, password-specific hashing algorithm such as Argon2id. If it's not available, bcrypt or another appropriate password hashing algorithm can be used.

// lib/auth/hash-password.ts
import bcrypt from "bcryptjs";

const SALT_ROUNDS = 12;

export async function hashPassword(plainPassword: string): Promise<string> {
  return bcrypt.hash(plainPassword, SALT_ROUNDS);
}

export async function verifyPassword(
  plainPassword: string,
  hashedPassword: string
): Promise<boolean> {
  return bcrypt.compare(plainPassword, hashedPassword);
}

What's happening here: bcrypt.hash() doesn't just scramble the password — it applies a slow, computationally expensive algorithm on purpose, which increases the cost of each password guess and makes large-scale brute-force attacks significantly more expensive. SALT_ROUNDS = 12 is above OWASP's minimum bcrypt work factor of 10, but the right value depends on your server's hardware and traffic. Benchmark your production environment and choose a cost that makes password verification sufficiently expensive without creating unacceptable latency.

⚠️ bcrypt limitation: bcrypt has a hard 72-byte input limit, and most implementations (including bcryptjs) silently truncate anything past it rather than erroring. Because UTF-8 characters like emoji or accented letters can take up to 4 bytes each, a password that looks well under the limit in characters can still get silently cut short in bytes — which can cause two different passwords to be treated as equivalent after truncation.
OWASP currently recommends enforcing a maximum of 72 bytes (or less, depending on the implementation) when bcrypt is used. Because UTF-8 characters can occupy multiple bytes, a character-count limit alone doesn't necessarily correspond to bcrypt's byte limit.

⚠️ Common Mistake: Comparing passwords with a plain === check after "encrypting" them with something reversible like Base64. That's encoding, not hashing — it can be reversed instantly. Only use a dedicated password-hashing library.

2. Session-Based Authentication

After a successful login, the server creates a session record stored in server-side session storage such as a database or shared cache — and gives the browser a random session ID in an httpOnly cookie. On every request, the server looks up that ID to know who's logged in.

// lib/auth/session.ts
import { cookies } from "next/headers";
import { randomUUID } from "crypto";

export async function createSession(userId: string, expiresAt: Date) {
  // Generate a random, unguessable session ID — never store the raw
  // userId (or anything else predictable) directly as the cookie's
  // value. The cookie is a reference you look up server-side; it
  // should never double as proof of identity on its own.
  const sessionId = randomUUID();

  // Persist the mapping server-side, e.g.:
  // await db.session.create({ data: { sessionId, userId, expiresAt } });

  const cookieStore = await cookies();

  cookieStore.set("session_id", sessionId, {
    httpOnly: true,
    secure: true,
    sameSite: "lax",
    expires: expiresAt,
    path: "/",
  });
}

Why each flag matters: httpOnly stops client-side JavaScript from reading the cookie (blocking a common XSS attack path). secure means it's only sent over HTTPS. sameSite: "lax" limits when the browser sends the cookie in cross-site requests and provides some CSRF protection. For state-changing operations, you should still implement an appropriate CSRF defense rather than relying on SameSite alone.

Pros: straightforward server-side revocation; deleting a session record can invalidate that session immediately, and deleting all of a user's sessions can log them out everywhere.
Cons: can require a server-side session lookup on authenticated requests, although caching can reduce the cost.

3. Token-Based Authentication (JWT)

Instead of looking anything up server-side, a JSON Web Token (JWT) packs the user's identity directly into a signed token. In a stateless JWT design, the server can verify the token cryptographically without looking up a session record in the database.

// lib/auth/jwt.ts
import { SignJWT, jwtVerify } from "jose";

const secretKey = new TextEncoder().encode(process.env.AUTH_SECRET);

export async function signToken(userId: string, expiresAt: Date) {
  return new SignJWT({})
    .setProtectedHeader({ alg: "HS256" })
    .setSubject(userId)
    .setIssuedAt()
    .setExpirationTime(expiresAt)
    .sign(secretKey);
}

export async function verifyToken(token: string) {
  try {
    const { payload } = await jwtVerify(token, secretKey, {
      algorithms: ["HS256"],
    });
    return payload;
  } catch {
    return null; // invalid or expired
  }
}

What's happening here: jose is the standard, actively maintained library for signing and verifying JWTs using the Web Crypto API — it works in Node.js, edge runtimes, and browsers. setSubject(userId) stores the user's ID in the token's standard sub claim. jwtVerify() automatically rejects the token if the signature doesn't match or if it's expired, so you never write manual expiry checks.

⚠️ Signing is not encryption. A JWT's payload is only base64url-encoded, not encrypted — anyone can decode and read it. The signature only proves it wasn't tampered with. Never put sensitive data (passwords, secrets) inside a JWT payload.

Pros: no database lookup needed to verify identity, works well across distributed/stateless servers.
Cons: harder to instantly revoke a single token before it expires (it's valid until it naturally expires unless you build extra machinery around it).

💡 For a deeper side-by-side of these two models — including how each behaves at scale — see Session vs JWT: Which Should You Use in Next.js 16?

OAuth 2.0 is an authorization framework that lets an application obtain limited access to resources on behalf of a user. It doesn't, by itself, define how an application verifies the user's identity.

For "Sign in with Google," "Sign in with Microsoft," and similar login flows, applications commonly use OpenID Connect (OIDC) — an identity layer built on top of OAuth 2.0. The identity provider authenticates the user and returns an ID token containing claims about that authentication.

User clicks "Sign in with GitHub"
        ↓
Redirected to GitHub
        ↓
User authenticates and approves access
        ↓
GitHub redirects back with a code
        ↓
Your server exchanges the code for tokens
        ↓
Your server validates the OIDC identity information
        ↓
Your app creates its own session

This is why OAuth is so popular for beginners and production apps alike — you outsource the hardest parts (password storage, breach risk, 2FA) to a provider that already does it well.

5. Multi-Factor Authentication (MFA / 2FA)

MFA requires more than one proof of identity — typically "something you know" (a password) plus "something you have" (a phone, an authenticator app code, a hardware key). Even if a password leaks, the attacker still can't get in without the second factor.

6. Passwordless Authentication (Magic Links & Passkeys)

Two increasingly common alternatives to passwords:

Magic links — the user enters their email, gets a one-time sign-in link, and clicking it logs them in. No password to remember or leak.
Passkeys (WebAuthn) — device-based authentication using Face ID, Windows Hello, or a hardware security key. No shared secret exists to steal in the first place, which makes passkeys resistant to phishing in a way passwords fundamentally aren't.

A Minimal Authentication Flow in Next.js

Here's a simplified but realistic login flow using Next.js 16, TypeScript, and session cookies — the same core pattern used by most production apps, just without the database wiring.

// actions/login.ts
"use server";

import { redirect } from "next/navigation";
import { verifyPassword } from "@/lib/auth/hash-password";
import { createSession } from "@/lib/auth/session";
import { z } from "zod";

const loginSchema = z.object({
  email: z.email(),
  password: z.string().min(8),
});

export async function login(prevState: unknown, formData: FormData) {
  const parsed = loginSchema.safeParse({
    email: formData.get("email"),
    password: formData.get("password"),
  });

  if (!parsed.success) {
    return { error: "Enter a valid email and password." };
  }

  // Look up the user in your database (pseudocode)
  const user = await db.user.findUnique({ where: { email: parsed.data.email } });

  if (!user || !(await verifyPassword(parsed.data.password, user.passwordHash))) {
    // Same generic error for both cases — don't reveal which one was wrong
    return { error: "Invalid email or password." };
  }

  const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000); // 7 days
  await createSession(user.id, expiresAt);

  redirect("/dashboard");
}

What's happening here: the form data is validated with Zod before touching the database — never trust raw input. Notice the login failure returns the same generic message whether the email doesn't exist or the password is wrong; revealing which one failed makes it easier for attackers to enumerate valid accounts. A working session gets created only after the password check succeeds, then the user is redirected.

⚠️ Common Mistake: Checking authentication only in proxy and assuming that's enough. Proxy-level checks are a good UX shortcut (fast redirect before a page even loads), but sensitive Server Actions, Route Handlers, and data-access functions should independently verify authentication and authorization rather than relying solely on proxy.ts.

Building this by hand is a great way to learn, but most production apps reach for a maintained library instead — see How to Add Auth.js (NextAuth v5) in Next.js 16, Add Clerk Authentication to Next.js 16, or (if you're already on Supabase) Supabase Auth vs Firebase Auth.

Common Authentication Mistakes to Avoid

Storing plain-text passwords — always hash with Argon2id or bcrypt, never store or log the raw password
Storing a predictable value as the session cookie — the cookie should be a random, unguessable reference, never the raw user ID or anything else an attacker could construct
Weak or reused session/JWT secrets — generate a long, random secret and never commit it to git
Revealing which field was wrong — "Invalid email" vs. "Invalid password" tells attackers an account exists
Skipping rate limiting — without it, attackers can brute-force passwords with unlimited attempts
Relying only on client-side checks — a hidden button or disabled form field doesn't stop a direct API request
Forgetting to expire sessions/tokens — every session and token should have a sane expiry, not live forever

Frequently Asked Questions

What is the difference between authentication and authorization?

Authentication confirms who someone is (logging in). Authorization decides what they're allowed to do once they're recognized (permissions, roles, access control). You always need authentication before authorization can happen.

Yes — a login system is simply the implementation of authentication. Whatever mechanism confirms a user's identity (password, OAuth, passkey) is functioning as authentication, regardless of what you call the feature.

What's the difference between sessions and JWTs?

A session stores authentication/session state on the server and gives the browser only a random reference ID, which allows instant revocation. A JWT stores the identity data directly inside a signed token the server can verify without a database lookup, trading easy revocation for less server-side state.

Keep JWT minimal — a JWT should not be treated as a general-purpose user profile or database replacement.

Do I need a library to build authentication, or can I build it myself?

You can build basic password + session authentication yourself using the patterns above, but for anything production-facing, an established library (Auth.js, Clerk, Better Auth, or your database provider's built-in auth) is strongly recommended — they handle edge cases like token rotation, breach detection, and secure defaults that are easy to get subtly wrong by hand.

Is two-factor authentication (2FA) actually necessary?

For anything holding sensitive data — financial info, personal messages, admin access — yes. 2FA dramatically reduces account takeover risk even when a password leaks, since the attacker also needs the second factor.

Are passkeys better than passwords?

Generally yes, from a security standpoint — passkeys are phishing-resistant because there's no shared secret to trick someone into revealing. Adoption is still growing, though, so most apps currently offer passkeys as an option alongside passwords rather than a full replacement.

Wrapping Up

Authentication boils down to one question — "who are you?" — answered through a password, a token, a device, or some combination of them. Once you separate authentication from authorization, the ecosystem becomes easier to understand: passwords and passkeys are authentication mechanisms, sessions and JWTs are ways to maintain authenticated state, and OAuth/OIDC provide delegated authorization and federated identity.

If you're building this in a real Next.js app, the next logical steps are wiring up role-based authorization on top of your authentication layer, and deciding between session-based and JWT-based auth based on whether instant revocation matters for your product.

Continue Learning

Free Developer Tools

Zod Schema Generator — generate a validated schema for your role/permission payloads straight from a JSON sample or TypeScript interface, including a ready-to-use Server Action.
Supabase RLS Policy Generator — pair this guide's application-level RBAC with database-level Row Level Security. Generates owner-only, team, and admin-override policies with the auth.uid() performance wrapper built in.

Session vs JWT: Which Should You Use in Next.js 16?

Tue, 25 Aug 2026 04:12:26 +0000

You're building a login flow in Next.js 16, and you hit the question every auth tutorial glosses over: should the logged-in state live in a session or a JWT? Half the guides you find use one, half use the other, and almost none of them tell you why — or what breaks if you pick wrong.

Here's the annoying part: both approaches look nearly identical from the outside. A cookie gets set, the user stays logged in, everyone's happy. The difference only shows up later — when you need to log a user out of every device instantly, when your app scales past one server, or when you're debugging why a "revoked" user can still hit your API for another six days.

By the end of this guide, you'll know exactly how sessions and JWTs work under the hood, see real, working code for both in Next.js 16 — using jose, Server Actions, and proxy.ts — and know which one actually fits your project instead of copying whatever the last tutorial you read happened to use.

Why This Is Tricky

Most explanations of "session vs JWT" get stuck comparing them as if they're two totally separate technologies. They're not. In both approaches, the browser stores a cookie. The real difference is what that cookie contains, and where the source of truth lives:

Session-based auth: the cookie holds a random ID. The actual user data lives in your database. Every request that needs to know "who is this?" looks it up server-side.
JWT-based auth: the cookie holds the user data itself, cryptographically signed. Your server can verify it's untampered without ever touching a database.

That one distinction — lookup vs. self-contained — is what drives every tradeoff in this post: revocation, scaling, latency, and how much you need to trust the cookie itself.

💡 Tip: If you've used Auth.js (NextAuth v5), you've already used both without necessarily noticing — its session: { strategy: "jwt" } and session: { strategy: "database" } options are exactly this same choice, just configured for you.

Prerequisites

This guide uses:

Next.js 16 with the App Router
TypeScript in strict mode
React Compiler enabled (no manual useMemo/useCallback needed)
Tailwind CSS for the (minimal) UI examples

You don't need a real database to follow along — the JWT section has zero dependencies, and the session section uses a generic db client you can swap for Postgres, Supabase, or whatever you're already using.

How Sessions Work

💡 Think of it like: a coat check ticket. The ticket itself is just a number — it means nothing on its own. The actual coat (your user data) stays with the attendant (your database). Lose the ticket, and the attendant can also just... stop honoring it. Instantly.

User logs in with the right credentials.
Your server generates a random token, stores it in a sessions table alongside the user's ID and an expiry, and sends that token back as an httpOnly cookie.
On every request, your server takes the cookie value, looks it up in the database, and either finds a valid session or doesn't.
To log someone out — including forcibly, from your side — you delete the row. Done. The cookie is now worthless.

The tradeoff: every authenticated request costs a database round trip (unless you cache it), but you get instant, guaranteed revocation.

How JWTs Work

💡 Think of it like: a sealed, signed letter. Anyone can read what's inside once it's opened, but nobody can forge your signature or quietly edit the contents without breaking the seal. The letter is self-sufficient — you don't need to call anyone to confirm it's real, just check the seal.

User logs in with the right credentials.
Your server creates a token containing the user's ID (and whatever else you want) and signs it with a secret key.
On every request, your server checks the signature against that same secret. If it matches, the data inside is trusted — no database lookup required.
To log someone out, you delete the cookie client-side. But if someone already has a copy of that token, it's still valid — and still verifiable — until it naturally expires. There's no built-in way to say "actually, ignore this one."

The tradeoff: verification is fast and needs no database, but you give up the ability to instantly kill a single session without extra machinery.

⚠️ Common Mistake: Calling a JWT stored in a cookie a "session" and assuming it behaves like one. It doesn't — a JWT has no server-side record at all unless you deliberately build one (see the revocation section below). If your mental model is "session," you'll be surprised the first time you try to force-logout a user and nothing happens.

⚠️ Cookie size limits: browsers cap a single cookie at roughly 4KB, and most reverse proxies (Nginx, Cloudflare) reject requests once the total header size gets much past 8KB. A session-ID cookie is always tiny — it's just a random string. A JWT cookie grows with every claim you cram into the payload (roles, permissions, profile fields). Stuff enough into it and the cookie silently fails to set, or your CDN starts 400-ing requests, with no obvious error pointing back at "your JWT got too big." Keep JWT payloads minimal — an ID and maybe a role, not a serialized user object.

Step 1: Set Up the Shared Pieces

Both approaches need somewhere to keep a signing secret. Add one to your environment file:

# .env.local
SESSION_SECRET=your-long-random-secret-here

Generate a strong value instead of typing something memorable:

node -e "console.log(crypto.randomBytes(32).toString('hex'))"

⚠️ Common Mistake: Committing SESSION_SECRET to git, or reusing your .env.local value in production. Treat it exactly like a database password — if it leaks, an attacker can forge valid sessions for any user, for either approach below.

Step 2: Build JWT-Based Auth with `jose`

jose is the standard library for signing and verifying JWTs in an Edge-compatible way — it uses the Web Crypto API instead of Node's crypto module, so it works identically in Server Actions, Route Handlers, and proxy.ts.

npm install jose

Create the sign/verify helpers

// lib/jwt/session.ts
import "server-only";
import { SignJWT, jwtVerify } from "jose";

const secretKey = process.env.SESSION_SECRET;
const encodedKey = new TextEncoder().encode(secretKey);

export async function encrypt(userId: string, expiresAt: Date) {
  return new SignJWT({})
    .setProtectedHeader({ alg: "HS256" })
    .setSubject(userId) // sub — who this token belongs to
    .setIssuedAt() // iat — when it was issued
    .setExpirationTime(expiresAt) // exp — when it stops being valid
    .sign(encodedKey);
}

export async function decrypt(token: string | undefined = "") {
  try {
    const { payload } = await jwtVerify(token, encodedKey, {
      algorithms: ["HS256"],
    });
    return payload; // payload.sub is the userId; iat/exp are unix seconds
  } catch {
    // Invalid signature, tampered payload, or expired token
    return null;
  }
}

What's happening here: instead of a custom userId field, this uses the standard, registered JWT claims — sub (subject, via .setSubject()), iat (issued-at, via .setIssuedAt()), and exp (expiry, via .setExpirationTime()). These three are part of the JWT spec itself, not a jose-specific convention, so any JWT library — in any language — knows how to read them. jwtVerify automatically checks exp and rejects an expired token before your code ever sees the payload, so you never write manual date comparisons.

⚠️ Signing is not encryption. SignJWT — despite this file calling the wrapper functions encrypt/decrypt for readability — does not hide the payload. A JWT's contents are only base64url-encoded, not encrypted, so anyone who intercepts the cookie (or just opens DevTools → Application → Cookies) can decode and read sub, iat, and exp in plain text. What the signature guarantees is that the payload wasn't tampered with — change one character and jwtVerify rejects it. Never put anything genuinely secret (passwords, tokens for other services, PII you wouldn't want exposed) inside a signed JWT. If you actually need to hide the contents too, that's a different primitive — JWE — which jose supports separately via EncryptJWT/jwtDecrypt.

💡 Do you still need setExpirationTime if you also track expiry elsewhere? No — and the version above deliberately avoids the redundancy. Compute the expiry date once, and hand that same Date to both setExpirationTime() (for the JWT's own exp claim) and the cookie's expires option, as shown in the next step. Two separately-computed "7 days from now" values can drift apart by milliseconds and give you two conflicting sources of truth for the same thing — pick one.

// lib/jwt/actions.ts
"use server";

import { cookies } from "next/headers";
import { redirect } from "next/navigation";
import { encrypt } from "./session";

export async function createSession(userId: string) {
  const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000);
  const session = await encrypt(userId, expiresAt); // same Date used for exp and the cookie
  const cookieStore = await cookies();

  cookieStore.set("session", session, {
    httpOnly: true,
    secure: true,
    expires: expiresAt,
    sameSite: "lax",
    path: "/",
  });
}

export async function deleteSession() {
  const cookieStore = await cookies();
  cookieStore.delete("session");
  redirect("/login");
}

What's happening here: httpOnly: true keeps the cookie invisible to client-side JavaScript, which stops it from being stolen via an XSS attack. secure: true means it's only ever sent over HTTPS. sameSite: "lax" blocks the cookie from being attached to most cross-site requests, which is your main defense against CSRF here. None of this is JWT-specific — you'd want the exact same flags on a session-ID cookie too.

Verify the session with a Data Access Layer

Don't scatter decrypt() calls across every page. Centralize verification in one cached function — this is what Next.js's own docs call a Data Access Layer (DAL).

// lib/jwt/dal.ts
import "server-only";
import { cache } from "react";
import { cookies } from "next/headers";
import { redirect } from "next/navigation";
import { decrypt } from "./session";

export const verifySession = cache(async () => {
  const cookieStore = await cookies();
  const token = cookieStore.get("session")?.value;
  const session = await decrypt(token);

  if (!session?.sub) {
    redirect("/login");
  }

  return { isAuth: true, userId: session.sub };
});

What's happening here: wrapping this in React's cache() means that no matter how many components on the same page call verifySession(), the actual decrypt-and-check logic only runs once per request — every subsequent call reuses the result. session.sub is the standard claim set by .setSubject() earlier, so this reads it back out under a friendlier userId name for the rest of your app. Call this at the top of any Server Component, Server Action, or Route Handler that needs to know who's logged in.

// app/dashboard/page.tsx
import { verifySession } from "@/lib/jwt/dal";

export default async function DashboardPage() {
  const { userId } = await verifySession();

  return <h1>Welcome back, user {userId}</h1>;
}

Add an optimistic check in `proxy.ts`

In Next.js 16, middleware.ts was renamed to proxy.ts — same file convention, same idea. It's the first thing that runs before a request reaches a page, which makes it a good place for a fast, optimistic redirect. Full verification still happens in the DAL above — proxy.ts just avoids letting an obviously-unauthenticated request render a protected page at all.

// proxy.ts
import { NextRequest, NextResponse } from "next/server";

const protectedRoutes = ["/dashboard"];
const publicRoutes = ["/login", "/signup"];

export default function proxy(req: NextRequest) {
  const path = req.nextUrl.pathname;
  const isProtectedRoute = protectedRoutes.some((route) => path.startsWith(route));
  const isPublicRoute = publicRoutes.includes(path);

  // Optimistic check only — we just look for the cookie's presence.
  // We deliberately don't verify the signature here; that happens
  // in verifySession() inside the Data Access Layer.
  const cookie = req.cookies.get("session")?.value;

  if (isProtectedRoute && !cookie) {
    return NextResponse.redirect(new URL("/login", req.nextUrl));
  }

  if (isPublicRoute && cookie) {
    return NextResponse.redirect(new URL("/dashboard", req.nextUrl));
  }

  return NextResponse.next();
}

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
};

⚠️ Common Mistake: Treating proxy.ts as your only security check. It's a UX nicety that avoids a flash of protected content — it is not a substitute for re-verifying the session inside every Server Action and Route Handler that actually touches data. A request can always be sent directly, bypassing whatever page it "should" have come from.

Step 3: Build Database-Backed Sessions

Now the other approach — a real session table your server checks on each request.

Create the sessions table

-- Works for Postgres/Supabase; adjust types for your database
create table sessions (
  token_hash text primary key,
  user_id uuid not null references auth.users(id) on delete cascade,
  expires_at timestamptz not null,
  created_at timestamptz not null default now()
);

create index idx_sessions_user_id on sessions (user_id);

What's happening here: notice the primary key is token_hash, not token. We never store the raw session token in the database — only its hash. This mirrors how you'd never store a plaintext password: if your database ever leaked, an attacker with the hashes still couldn't reconstruct a working cookie.

⚠️ Cleanup: expiring a session only stops it from being accepted — the expires_at < now() check in verifyDbSession below handles that. It does not delete the row. Left alone, this table grows forever, one row per login, most of them long past their expiry date. Run a scheduled cleanup — a Vercel Cron job hitting a small Route Handler once a day is enough for most apps:
delete from sessions where expires_at < now();
This is purely a housekeeping/performance concern (an unbounded table gets slower to index and back up over time), not a security one — an expired row is already useless for authentication either way.

// lib/db-session/create.ts
import "server-only";
import { randomBytes, createHash } from "crypto";
import { cookies } from "next/headers";
import { db } from "@/lib/db";

function hashToken(token: string) {
  return createHash("sha256").update(token).digest("hex");
}

export async function createDbSession(userId: string) {
  const token = randomBytes(32).toString("hex"); // goes to the browser
  const tokenHash = hashToken(token); // goes to the database
  const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000);

  await db.session.create({
    data: { tokenHash, userId, expiresAt },
  });

  const cookieStore = await cookies();
  cookieStore.set("session", token, {
    httpOnly: true,
    secure: true,
    sameSite: "lax",
    expires: expiresAt,
    path: "/",
  });
}

What's happening here: randomBytes(32) generates a token with enough entropy that guessing it is computationally infeasible — this is the piece doing the actual security work, not the hashing. We hash it with SHA-256 purely so a database leak doesn't hand out working session tokens; the browser still holds the real, unhashed token in its cookie.

Verify the session (with caching, so it doesn't hit the database on every render)

// lib/db-session/dal.ts
import "server-only";
import { cache } from "react";
import { cookies } from "next/headers";
import { createHash } from "crypto";
import { redirect } from "next/navigation";
import { db } from "@/lib/db";

function hashToken(token: string) {
  return createHash("sha256").update(token).digest("hex");
}

export const verifyDbSession = cache(async () => {
  const cookieStore = await cookies();
  const token = cookieStore.get("session")?.value;

  if (!token) redirect("/login");

  const tokenHash = hashToken(token);
  const session = await db.session.findUnique({
    where: { tokenHash },
    include: { user: true },
  });

  if (!session || session.expiresAt < new Date()) {
    redirect("/login");
  }

  return { isAuth: true, userId: session.userId, user: session.user };
});

What's happening here: just like the JWT version, cache() means one database lookup per request no matter how many components ask "who's logged in?" This is the piece that makes database sessions viable in practice — without it, a page with five components each checking auth would fire five identical queries.

Revoking a session — the whole point of this approach

// lib/db-session/delete.ts
"use server";

import { cookies } from "next/headers";
import { redirect } from "next/navigation";
import { createHash } from "crypto";
import { db } from "@/lib/db";

function hashToken(token: string) {
  return createHash("sha256").update(token).digest("hex");
}

export async function deleteDbSession() {
  const cookieStore = await cookies();
  const token = cookieStore.get("session")?.value;

  if (token) {
    await db.session.delete({ where: { tokenHash: hashToken(token) } }).catch(() => {});
  }

  cookieStore.delete("session");
  redirect("/login");
}

// Force-logout every session for a user — e.g. after a password reset
export async function revokeAllSessionsForUser(userId: string) {
  await db.session.deleteMany({ where: { userId } });
}

What's happening here: revokeAllSessionsForUser is the function you can't build with plain JWTs — one query, and every device that user is logged in on is instantly signed out, because the next request they make finds no matching row. This is the single biggest practical reason teams reach for database sessions over JWTs.

proxy.ts looks identical to the JWT version above — it's still just checking whether the session cookie exists, since that check never needed to know which auth strategy is behind it.

Session vs JWT: Side-by-Side

	Session (database)	JWT
Where the data lives	Server-side (database row)	Inside the token itself
Cookie contents	Random, meaningless ID	Signed, self-contained payload
Instant revocation	✅ Delete the row	❌ Not without extra machinery
Force-logout everywhere	✅ One query	❌ Requires a blocklist or short expiry + refresh
Per-request cost	One DB lookup (cacheable per request)	No DB call — just signature verification
Works well at scale / multi-server	Needs a shared database (usually already true)	Naturally stateless, nothing to share
Payload can go stale	No — always reads current data	Yes — data inside is frozen until re-issued
Implementation complexity	Slightly more (schema, hashing, cleanup)	Slightly less (no schema needed)
Best for	Apps where instant revocation matters <br/> (banking, admin tools, anything security-sensitive)	High-traffic, distributed systems where avoiding a <br/>DB hit per request matters

💡 Tip: "JWTs don't need a database" is true for verification, but most real apps still store something — a refresh-token table, a denylist, or at minimum a passwordChangedAt timestamp checked against the token's iat (issued-at) claim. The stateless promise of JWTs is a little softer in practice than it sounds in theory.

A Closer Look: What "Horizontal Scaling" Actually Means Here

"Naturally stateless" in the table above is doing a lot of work, so let's unpack it. Say your app runs on five server instances behind a load balancer — a request from the same user could land on a different instance every time.

With database sessions: whichever instance handles the request just needs to reach the same database everyone else does. In practice this is a non-issue for most Next.js apps, since you already have one shared database — every instance was already talking to it for everything else. The "scaling problem" people worry about here mostly doesn't exist unless you're deliberately running sessions in something instance-local, like in-memory storage (don't do that).
With JWTs: verification needs nothing but the signing secret, which every instance already has as an environment variable. No instance has to coordinate with any other instance, or with a database, to answer "is this token valid?" That's genuinely useful once you're running at the edge — Cloudflare Workers, Vercel Edge Functions — across multiple regions, where a round trip to a single-region database could add real, noticeable latency to every request.

So the honest version: for a typical app with one shared Postgres/Supabase database, this isn't really a deciding factor — you're already "horizontally scaled" for sessions for free. It starts to matter once you're running truly distributed, multi-region, or edge-first infrastructure where a database round trip per request is a real, measured cost, not a hypothetical one.

Sliding (Rolling) Sessions

So far, every example here uses a fixed expiry — log in, get 7 days, and after 7 days you're logged out no matter how active you were. A sliding session (also called a rolling session) instead extends the expiry every time the user does something, so an active user effectively never gets logged out, while an idle one still expires on schedule.

With database sessions, this is simple: on every successful verifyDbSession() call, update that row's expires_at to "now + 7 days" again.
```
// Inside verifyDbSession, after confirming the session is valid
await db.session.update({
  where: { tokenHash },
  data: { expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000) },
});
```
One extra write per (cached) verification — cheap, and the source of truth (the row) is already being touched anyway.

💡 Tip: In production it's common to only extend the session once every few hours instead of on every request to avoid unnecessary writes.

With JWTs, this is more work: the exp claim is baked into the signature at issue time — you can't quietly extend it without re-signing a brand-new token and setting a brand-new cookie on the response. Doable inside a Route Handler or Server Action (create a fresh token with a new expiresAt, call cookies().set() again), but it means writing a cookie back on requests that otherwise wouldn't need one, which is easy to forget to wire up consistently across every route.

💡 Tip: If "stay logged in while active, expire after a week of silence" is a real requirement for your app, that alone is a reasonable tie-breaker toward database sessions — it's a one-line update there versus meaningfully more plumbing with JWTs.

Can You Get Revocation With JWTs?

Yes, with a tradeoff. Two common patterns:

Short expiry + refresh tokens. Issue an access token that expires in 10–15 minutes, plus a longer-lived refresh token stored in the database. To revoke, you delete the refresh token — the access token is still technically valid, but only for a few more minutes, which is an acceptable blast radius for most apps.
A denylist. Keep a small, fast-to-check store (Redis is the usual choice) of token IDs (jti claims) that have been explicitly revoked. Every verification also checks this list. This reintroduces a lookup on every request — at that point, you've mostly reinvented database sessions with extra steps.

Neither of these makes JWTs behave exactly like sessions — they just narrow the gap. If instant, guaranteed revocation is a hard requirement (think: a compromised admin account), database sessions remove the problem entirely instead of managing around it.

Which One Should You Actually Use?

Building a typical SaaS dashboard, internal tool, or content site? Database sessions. The DB hit is cheap with caching, and "log this user out right now" is a feature you'll eventually need, even if you don't think so today.
Building something with genuinely massive, distributed, stateless traffic (think: an API consumed by thousands of independent clients, or infrastructure where adding a database round trip to every request is a real cost)? JWTs earn their keep here.
Already using Auth.js or Clerk? You don't have to choose by hand — Auth.js exposes session: { strategy: "jwt" | "database" } directly, and Clerk manages this decision for you behind its own infrastructure.
Not sure yet? Default to database sessions. It's the safer, more debuggable choice, and the performance cost is rarely the bottleneck people assume it'll be — cache the lookup with cache() as shown above and it disappears from your profiler.

Frequently Asked Questions

Can I combine both approaches?

Yes — this is actually what "refresh tokens" are: a short-lived JWT for fast verification, backed by a database-stored refresh token for revocation. You get JWT-speed reads most of the time, with a real revocation point when you need one.

No, and the difference matters for security. An httpOnly cookie can't be read by client-side JavaScript, so it's protected from XSS attacks that steal tokens. localStorage is fully readable by any script running on your page — a single XSS vulnerability anywhere in your dependency tree can leak every token stored there. Always use httpOnly cookies for auth tokens in a Next.js app.

Does `proxy.ts` need to fully verify the session on every request?

No, and for JWT-based auth verifying in proxy.ts with jose is genuinely fine performance-wise since it needs no database call. The stronger rule is: never treat proxy.ts as your only check. Always re-verify inside the Server Action or Route Handler that actually reads or writes data — proxy.ts can be bypassed by hitting that endpoint directly.

Why hash the session token before storing it in the database?

The same reason you hash passwords — if your database is ever compromised (a leaked backup, a misconfigured access policy), the attacker gets a list of hashes they can't turn back into working session cookies. It costs you one sha256 call per request, which is effectively free.

Which one does Auth.js use by default?

Auth.js defaults to the "jwt" strategy unless you configure a database adapter, in which case it switches to "database" automatically. You can also set session: { strategy: "jwt" } explicitly even with an adapter configured, if you want JWTs for speed while still persisting user accounts.

Wrapping Up

Sessions and JWTs aren't competing standards — they're two different answers to "where does the source of truth for a logged-in user live?" Sessions keep it on your server, trading a database lookup for instant, total control over who stays logged in. JWTs keep it in the token itself, trading that control for verification that never has to leave the request.

For most Next.js apps, start with database sessions — the caching pattern above keeps the performance cost near zero, and you'll be glad revocation is a solved problem the first time you actually need it. Reach for JWTs specifically when you've measured that the database hit matters, not because a tutorial defaulted to it.

From here, a natural next step is wiring either pattern into a real login form with Zod validating the credentials before they ever reach your session logic, or layering role-based permissions on top of whichever session strategy you pick.

Coder Legion - Recent posts tagged sessions

What Is Authentication? A Beginner's Guide (2026)

What Is Authentication? (Quick Answer)

Why Authentication Matters

Authentication vs. Authorization: The Difference That Trips Everyone Up

How Authentication Works (Step by Step)

The Main Types of Authentication

1. Password-Based Authentication

2. Session-Based Authentication

3. Token-Based Authentication (JWT)

4. OAuth / OpenID Connect (Social Login)

5. Multi-Factor Authentication (MFA / 2FA)

6. Passwordless Authentication (Magic Links & Passkeys)

A Minimal Authentication Flow in Next.js

Common Authentication Mistakes to Avoid

Frequently Asked Questions

What is the difference between authentication and authorization?

Is a login system the same thing as authentication?

What's the difference between sessions and JWTs?

Do I need a library to build authentication, or can I build it myself?

Is two-factor authentication (2FA) actually necessary?

Are passkeys better than passwords?

Wrapping Up

Continue Learning

Free Developer Tools

Session vs JWT: Which Should You Use in Next.js 16?

Why This Is Tricky

Prerequisites

How Sessions Work

How JWTs Work

Step 1: Set Up the Shared Pieces

Step 2: Build JWT-Based Auth with jose

Create the sign/verify helpers

Create the session cookie on login

Verify the session with a Data Access Layer

Add an optimistic check in proxy.ts

Step 3: Build Database-Backed Sessions

Create the sessions table

Create the session on login

Verify the session (with caching, so it doesn't hit the database on every render)

Revoking a session — the whole point of this approach

Session vs JWT: Side-by-Side

A Closer Look: What "Horizontal Scaling" Actually Means Here

Sliding (Rolling) Sessions

Can You Get Revocation With JWTs?

Which One Should You Actually Use?

Frequently Asked Questions

Can I combine both approaches?

Is storing a JWT in a cookie the same as storing it in localStorage?

Does proxy.ts need to fully verify the session on every request?

Why hash the session token before storing it in the database?

Which one does Auth.js use by default?

Wrapping Up

Continue Learning

Useful Resources

Step 2: Build JWT-Based Auth with `jose`

Add an optimistic check in `proxy.ts`

Does `proxy.ts` need to fully verify the session on every request?