Customize your session token

Session tokens are JWTs generated by Clerk on behalf of your instance, and convey an authenticated user session to your backend.

Session tokens typically contain a standard set of claims that are required for Clerk to function. You can learn more about these default claims in the session tokens documentation.

This guide will show you how to customize a session token to include additional claims that you may need in your application.

The entire session token has a max size of 4kb. Exceeding this size can have adverse effects, including a possible infinite redirect loop for users who exceed this size on Next applications.

How to customize your session token

Go to Sessions in the Clerk Dashboard

In the Clerk Dashboard, navigate to the Sessions(opens in a new tab) page.

Click the Edit button

In the section titled Customize your session token, click on the Edit button.

Clerk Dashboard with an arrow pointing to the edit

Add a new claim to the session token

In the modal that opens, you can add any claim to your session token that you need. This examples adds a new claim called fullName and primaryEmail to the session token.

Clerk Dashboard showing the custom claim modal

Using the custom claims in your application

Now that you have added the custom claims to your session token, you can use them in your application. Below is an example of how you can use the getAuth helper to access the custom claims in your Next.js application.

Using `getAuth` in your Next.js application

app/page.[jsx/tsx]
import { auth } from '@clerk/nextjs';
import { NextResponse } from 'next/server';
 
export default function Page() {
  const { sessionClaims } = auth();
 
  const firstName = sessionClaims?.fullName;
 
  const primaryEmail = sessionClaims?.primaryEmail;
 
  return NextResponse.json({ firstName, primaryEmail })
}

pages/api/example.[ts/js]
import { getAuth } from "@clerk/nextjs/server";
import type { NextApiRequest, NextApiResponse } from 'next';
 
export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const { sessionClaims } = getAuth(req);
 
  const firstName = sessionClaims.fullName;
 
  const primaryEmail = sessionClaims.primaryEmail;
 
  return res.status(200).json({ firstName, primaryEmail })
}

Add global TypeScript type for additional session claims

A global type for additional session claims defined in a declaration file avoids type errors and provides auto-completion.

types/globals.d.ts
export { };
 
declare global {
  interface CustomJwtSessionClaims {
    firstName?: string;
    primaryEmail?: string;
  }
}