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
- In the Clerk Dashboard, navigate to the Sessions page.
- In the Customize your session token section, select Edit.
- 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 includes a sessionClaims
property that contains the custom claims you added to your session token. It's returned by the auth()
and getAuth()
helpers, and the request
object in server contexts.
The following example demonstrates how to access the fullName
and primaryEmail
claims that were added to the session token in the last step. This examples are written for Next.js, but they can be adapted to other frameworks by using the appropriate method for accessing the Auth
object.
import { auth } from '@clerk/nextjs/server'
import { NextResponse } from 'next/server'
export async function GET() {
const { sessionClaims } = await auth()
const fullName = sessionClaims?.fullName
const primaryEmail = sessionClaims?.primaryEmail
return NextResponse.json({ fullName, 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 fullName = sessionClaims.fullName
const primaryEmail = sessionClaims.primaryEmail
return res.status(200).json({ fullName, 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
types
directory. - Inside of the
types
directory, add aglobals.d.ts
file. - Create the
CustomJwtSessionClaims
interface and declare it globally. - Add the custom claims to the
CustomJwtSessionClaims
interface.
The following example demonstrates how to add the fullName
and primaryEmail
claims to the CustomJwtSessionClaims
interface.
export {}
declare global {
interface CustomJwtSessionClaims {
fullName?: string
primaryEmail?: string
}
}
Feedback
Last updated on