Skip to main content

Using the Next.js middleware


This method is an alternative method for using sessions in an API. If you are already using session guards, you can skip this step.

Setting up the middleware#

In the middleware we check if a session exists using the withSession helper function and set the user's user id to the request headers using the session object. You can set other information in the same way.


You cannot pass the full session container through the middleware because the Next.js middleware does not allow objects to be passed. If you need to access the full session container in your APIs switch to using session guards.

import { withSession } from "supertokens-node/nextjs";
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import { SessionContainer } from 'supertokens-node/recipe/session';
import { ensureSuperTokensInit } from "./app/config/backend";


export async function middleware(
request: NextRequest & { session?: SessionContainer }
) {
if (request.headers.has("x-user-id")) {
console.warn("The FE tried to pass x-user-id, which is only supposed to be a backend internal header. Ignoring.");

if (request.nextUrl.pathname.startsWith('/api/auth')) {
* /api/auth/* endpoints are exposed by the SuperTokens SDK,
* we do not want to modify the request for these routes

return withSession(request, async (err, session) => {
if (err) {
return NextResponse.json(err, { status: 500 });
if (session === undefined) {
headers: {
// You cannot attach the full session object here
'x-user-id': session.getUserId(),

export const config = {
matcher: '/api/:path*',

Fetching the user ID in your APIs#

The middleware will run for all routes, we can read information set by the middleware in the API routes:

import { NextResponse, NextRequest } from "next/server";
import { ensureSuperTokensInit } from '../../config/backend';


export function GET(request: NextRequest) {
const userId = request.headers.get("x-user-id");

// The middleware only adds the userId if a session exists
if (userId === null) {
return new NextResponse("Authentication required", { status: 401 });

return NextResponse.json({

This creates a GET request for the /api/userid route which returns the user id of the currently logged in user.

Looking for older versions of the documentation?
Which UI do you use?
Custom UI
Pre built UI