Which UI do you use?

Custom UI

Pre built UI

Using the Next.js middleware

CAUTION

This guide only applies to scenarios which involve SuperTokens Session Access Tokens.

If you are implementing either, Unified Login or Microservice Authentication, features that make use of OAuth2 Access Tokens, please check the separate page that shows you how to verify those types of tokens.

important

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.

caution

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.

middleware.ts

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";

ensureSuperTokensInit();

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.");
    request.headers.delete("x-user-id");
  }

  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 NextResponse.next()
  }

  return withSession(request, async (err, session) => {
    if (err) {
      return NextResponse.json(err, { status: 500 });
    }
    if (session === undefined) {
      return NextResponse.next()
    }
    return NextResponse.next({
      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:

app/api/userid/route.ts

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

ensureSuperTokensInit();

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({
    userId,
  });
}

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