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.
By default, session tokens contain 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.
Add custom claims to your session token
- Navigate to the Clerk Dashboard and select your application.
- In the navigation sidebar, select Sessions.
- In the Customize your session token section, click the Edit button.
- In the modal that opens, you can add any claim to your session token that you need.
The following example adds the fullName and primaryEmail claims to the session token.
Use the custom claims in your application
The Auth object in the @clerk/nextjs package includes a sessionClaims property that contains the custom claims you added to your session token.
Access the custom claims in your application by calling auth() in App Router applications or getAuth(req) in Pages Router applications.
The following example demonstrates how to access the fullName and primaryEmail claims that were added to the session token in the last step.
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 })
}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 custom session claims
To get auto-complete and prevent TypeScript errors when working with custom session claims, you can define a global type.
- In your application's root folder, add a
typesdirectory. - Inside of the
typesdirectory, add aglobals.d.tsfile. - Create the
CustomJwtSessionClaimsinterface and declare it globally. - Add the custom claims to the
CustomJwtSessionClaimsinterface.
The following example demonstrates how to add the firstName and primaryEmail claims to the CustomJwtSessionClaims interface.
export { };
declare global {
interface CustomJwtSessionClaims {
firstName?: string;
primaryEmail?: string;
}
}Feedback
Last updated on