Skip to main content
The updateSession method updates the session data for the currently authenticated user. An error is thrown if the user does not have an active session.

​
Method Signatures

// Server Actions, Route Handlers (not Server Components)
await auth0.updateSession(
  session: SessionData
): Promise<void>

​
Parameters

​
req
IncomingMessage | NextApiRequest | NextRequest
The request object (Pages Router and middleware only)
​
res
ServerResponse | NextApiResponse | NextResponse
The response object (Pages Router and middleware only)
​
session
SessionData
required
The updated session data to persist
interface SessionData {
  user: User;
  tokenSet: TokenSet;
  internal: {
    createdAt: number;
  };
  [key: string]: any; // Custom claims
}

​
Returns

Returns a Promise<void>. The method completes when the session has been updated.

​
Usage Examples

​
App Router

import { NextResponse } from 'next/server';
import { auth0 } from '@/lib/auth0';

export async function POST() {
  const session = await auth0.getSession();

  if (!session) {
    return NextResponse.json(
      { error: 'Unauthorized' },
      { status: 401 }
    );
  }

  // Update session with custom data
  await auth0.updateSession({
    ...session,
    customClaim: 'new value',
    lastUpdated: Date.now()
  });

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

​
Pages Router

import type { NextApiRequest, NextApiResponse } from 'next';
import { auth0 } from '@/lib/auth0';

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const session = await auth0.getSession(req);

  if (!session) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  // Update session
  await auth0.updateSession(req, res, {
    ...session,
    lastActivity: Date.now()
  });

  res.json({ success: true });
}

​
Middleware

middleware.ts
import { NextRequest, NextResponse } from 'next/server';
import { auth0 } from '@/lib/auth0';

export async function middleware(request: NextRequest) {
  const authRes = await auth0.middleware(request);

  if (request.nextUrl.pathname.startsWith('/auth')) {
    return authRes;
  }

  const session = await auth0.getSession(request);

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

  // Add request metadata to session
  await auth0.updateSession(request, authRes, {
    ...session,
    lastPath: request.nextUrl.pathname,
    lastVisit: Date.now()
  });

  return authRes;
}

​
Common Use Cases

​
Adding Custom Claims

const session = await auth0.getSession();

if (session) {
  await auth0.updateSession({
    ...session,
    role: 'admin',
    permissions: ['read', 'write', 'delete'],
    theme: 'dark'
  });
}

​
Tracking User Activity

const session = await auth0.getSession();

if (session) {
  await auth0.updateSession({
    ...session,
    lastActivity: new Date().toISOString(),
    pageViews: (session.pageViews || 0) + 1
  });
}

​
Storing Feature Flags

const session = await auth0.getSession();

if (session) {
  await auth0.updateSession({
    ...session,
    features: {
      betaAccess: true,
      darkMode: true
    }
  });
}

​
Updating User Metadata

const session = await auth0.getSession();

if (session) {
  await auth0.updateSession({
    ...session,
    user: {
      ...session.user,
      nickname: 'NewNickname',
      metadata: {
        favoriteColor: 'blue'
      }
    }
  });
}

​
Important Notes

Session updates are temporary. Any changes made via updateSession will be overwritten when the user re-authenticates and obtains a new session from Auth0.For persistent user data, update the user profile in Auth0 via the Management API.
Cannot be used in Server Components. The updateSession method requires the ability to set cookies, which is not possible in Server Components.Use Route Handlers or Server Actions instead.
The internal property containing session creation timestamp is preserved automatically. You don’t need to manually include it:
await auth0.updateSession({
  ...session,
  customData: 'value'
  // internal.createdAt is preserved automatically
});
In middleware, you must pass both the request and response objects to ensure session updates can be read within the same request.

​
Error Handling

The method throws an error when:
  • User has no active session
  • Session data is missing or invalid
try {
  await auth0.updateSession(updatedSession);
} catch (error) {
  console.error('Failed to update session:', error);
  // Handle error (e.g., redirect to login)
}

​
Pages Router Middleware Integration

When using Pages Router and reading session updates in the same request:
middleware.ts
import { NextRequest, NextResponse } from 'next/server';
import { auth0 } from '@/lib/auth0';

export async function middleware(request: NextRequest) {
  const authRes = await auth0.middleware(request);

  const session = await auth0.getSession(request);

  if (session) {
    await auth0.updateSession(request, authRes, {
      ...session,
      updatedAt: Date.now()
    });
  }

  // Combine headers to ensure updates are propagated
  const resWithCombinedHeaders = NextResponse.next({
    request: {
      headers: request.headers
    }
  });

  authRes.headers.forEach((value, key) => {
    resWithCombinedHeaders.headers.set(key, value);
  });

  return resWithCombinedHeaders;
}

​
Session Storage

Session updates are persisted differently based on your session store configuration:

​
Stateless Sessions (Default)

Updates are encrypted and stored in cookies: 
// Cookie size warning logged if session exceeds 4KB

​
Stateful Sessions

Updates are stored in your configured database:
lib/auth0.ts
import { Auth0Client } from '@auth0/nextjs-auth0/server';
import { RedisStore } from './redis-store';

export const auth0 = new Auth0Client({
  sessionStore: new RedisStore()
});
See Session Stores for implementation details.

getSession

Retrieve current session

Session Stores

Configure session storage

Build docs developers (and LLMs) love

Get started for freeTalk to us