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.

They typically contain a standard set of claims that are required for Clerk to function. However, you can customize them and retrieve the data at any point.

Clerk has default claims that will be included in this session token. You can read about Clerk's session tokens and it's default claims.

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