JWT Authentication | Bootspring Docs

Patterns for JWT (JSON Web Token) handling and validation in Next.js.

Overview#

JWT provides stateless authentication with:

Self-contained tokens with claims
No server-side session storage required
Edge-compatible verification
Cryptographic signature validation

Prerequisites:

Understanding of token-based auth
Secure secret key management

Installation#

npm install jose

# .env.local
JWT_SECRET=your-secure-secret-key-min-32-chars

Implementation#

JWT Session Creation#

// lib/session.ts
import { SignJWT, jwtVerify } from 'jose'
import { cookies } from 'next/headers'

const secret = new TextEncoder().encode(process.env.JWT_SECRET)
const COOKIE_NAME = 'session'

export async function createSession(userId: string) {
  const token = await new SignJWT({ userId })
    .setProtectedHeader({ alg: 'HS256' })
    .setIssuedAt()
    .setExpirationTime('7d')
    .sign(secret)

  cookies().set(COOKIE_NAME, token, {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'lax',
    maxAge: 60 * 60 * 24 * 7, // 7 days
    path: '/'
  })

  return token
}

Session Verification#

// lib/session.ts
export async function getSession() {
  const token = cookies().get(COOKIE_NAME)?.value

  if (!token) return null

  try {
    const { payload } = await jwtVerify(token, secret)
    return payload as { userId: string }
  } catch {
    return null
  }
}

export async function requireSession() {
  const session = await getSession()

  if (!session) {
    throw new Error('Unauthorized')
  }

  return session
}

Session Refresh#

// lib/session.ts
export async function refreshSession() {
  const session = await getSession()

  if (!session) return null

  // Create new token with extended expiry
  return createSession(session.userId)
}

Session Destruction#

// lib/session.ts
export async function destroySession() {
  cookies().delete(COOKIE_NAME)
}

JWT Middleware#

// middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
import { jwtVerify } from 'jose'

const secret = new TextEncoder().encode(process.env.JWT_SECRET)

export async function middleware(request: NextRequest) {
  const token = request.cookies.get('session')?.value

  if (!token) {
    return NextResponse.redirect(new URL('/login', request.url))
  }

  try {
    await jwtVerify(token, secret)
    return NextResponse.next()
  } catch {
    return NextResponse.redirect(new URL('/login', request.url))
  }
}

export const config = {
  matcher: ['/dashboard/:path*', '/settings/:path*']
}

API Token Authentication#

// lib/api-auth.ts
import { jwtVerify, SignJWT } from 'jose'

const secret = new TextEncoder().encode(process.env.JWT_SECRET)

export async function verifyApiToken(token: string) {
  try {
    const { payload } = await jwtVerify(token, secret)
    return payload
  } catch {
    return null
  }
}

export async function createApiToken(payload: Record<string, unknown>) {
  return new SignJWT(payload)
    .setProtectedHeader({ alg: 'HS256' })
    .setIssuedAt()
    .setExpirationTime('30d')
    .sign(secret)
}

API Route with JWT Auth#

// app/api/protected/route.ts
import { NextResponse } from 'next/server'
import { verifyApiToken } from '@/lib/api-auth'

export async function GET(request: Request) {
  const authHeader = request.headers.get('authorization')
  const token = authHeader?.replace('Bearer ', '')

  if (!token) {
    return NextResponse.json(
      { error: 'Missing authorization token' },
      { status: 401 }
    )
  }

  const payload = await verifyApiToken(token)

  if (!payload) {
    return NextResponse.json(
      { error: 'Invalid or expired token' },
      { status: 401 }
    )
  }

  return NextResponse.json({ data: 'Protected data', user: payload })
}

Usage Examples#

// app/api/login/route.ts
import { NextResponse } from 'next/server'
import { createSession } from '@/lib/session'
import { prisma } from '@/lib/db'
import bcrypt from 'bcryptjs'

export async function POST(request: Request) {
  const { email, password } = await request.json()

  const user = await prisma.user.findUnique({
    where: { email }
  })

  if (!user || !await bcrypt.compare(password, user.password)) {
    return NextResponse.json(
      { error: 'Invalid credentials' },
      { status: 401 }
    )
  }

  await createSession(user.id)

  return NextResponse.json({ success: true })
}

Protected Server Action#

// actions/user.ts
'use server'

import { requireSession } from '@/lib/session'
import { prisma } from '@/lib/db'

export async function getUserProfile() {
  const session = await requireSession()

  return prisma.user.findUnique({
    where: { id: session.userId }
  })
}

Best Practices#

Use strong secrets - Minimum 32 characters, randomly generated
Set short expiration - Balance security vs. user experience
Use httpOnly cookies - Prevent XSS access to tokens
Enable secure flag - Only send over HTTPS in production
Implement refresh tokens - For longer sessions, use refresh token rotation
Handle token errors - Gracefully handle expired/invalid tokens

Session Management - Advanced session handling
NextAuth.js - NextAuth.js with JWT strategy
MFA - Multi-factor authentication