Skip to main content
Docs

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.

Caution

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 in Next.js applications. It's recommended to move particularly large claims out of the JWT and fetch these using a separate API call from your backend. Learn more.

Add custom claims to your session token

  1. In the Clerk Dashboard, navigate to the Sessions page.
  2. Under Customize session token, in the Claims editor, you can add any claim to your session token that you need and select Save.

The following example adds the fullName and primaryEmail claims to the session token.

Clerk Dashboard showing the custom claim modal

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. Accessing the Auth object differs depending on the framework you are using. See the reference doc for more information.

The following example demonstrates how to access the fullName and primaryEmail claims that were added to the session token in the last step.

For Next.js, the Auth object is accessed using the auth() helper in App Router apps and the getAuth() function in Pages Router apps. Learn more about using these helpers.

app/api/example/route.tsx
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 })
}
pages/api/example.ts
import { getAuth } from '@clerk/nextjs/server'
import type { NextApiRequest, NextApiResponse } from 'next'

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  // Use `getAuth()` to get the user's ID and session claims
  const { sessionClaims } = getAuth(req)

  const fullName = sessionClaims.fullName

  const primaryEmail = sessionClaims.primaryEmail

  return res.status(200).json({ fullName, primaryEmail })
}

For Astro, the Auth object is accessed using the locals.auth() function. Learn more about using locals.auth().

src/api/example.ts
import type { APIRoute } from 'astro'

export const GET: APIRoute = async ({ locals }) => {
  // Use `locals.auth()` to get the user's ID and session claims
  const { userId, sessionClaims } = await locals.auth()

  // Protect the route by checking if the user is signed in
  if (!userId) {
    return new Response('Unauthorized', { status: 401 })
  }

  const fullName = sessionClaims.fullName

  const primaryEmail = sessionClaims.primaryEmail

  return new Response(JSON.stringify({ fullName, primaryEmail }))
}

For Express, the Auth object is accessed using the getAuth() function. Learn more about using getAuth().

import { clerkMiddleware, getAuth, requireAuth } from '@clerk/express'
import express from 'express'

const app = express()
const PORT = 3000

// Apply `clerkMiddleware()` to all routes
app.use(clerkMiddleware())

// Use `getAuth()` to get the session claims
const getSessionClaims = (req, res, next) => {
  const { sessionClaims } = getAuth(req)

  const fullName = sessionClaims.fullName

  const primaryEmail = sessionClaims.primaryEmail

  return res.status(200).json({ fullName, primaryEmail })
}

app.get('/profile', requireAuth(), getSessionClaims)

// Start the server and listen on the specified port
app.listen(PORT, () => {
  console.log(`Server is running on http://localhost:${PORT}`)
})

For React Router, the Auth object is accessed using the getAuth() function. Learn more about using getAuth().

src/routes/profile.tsx
import { redirect } from 'react-router'
import { getAuth } from '@clerk/react-router/ssr.server'
import { createClerkClient } from '@clerk/react-router/api.server'
import type { Route } from './+types/profile'

export async function loader(args: Route.LoaderArgs) {
  // Use `getAuth()` to get the user's ID and session claims
  const { userId, sessionClaims } = await getAuth(args)

  // Protect the route by checking if the user is signed in
  if (!userId) {
    return redirect('/sign-in?redirect_url=' + args.request.url)
  }

  const fullName = sessionClaims.fullName

  const primaryEmail = sessionClaims.primaryEmail

  return {
    fullName: JSON.stringify(fullName),
    primaryEmail: JSON.stringify(primaryEmail),
  }
}

export default function Profile({ loaderData }: Route.ComponentProps) {
  return (
    <div>
      <p>Welcome {loaderData.fullName}</p>
      <p>Your email is {loaderData.primaryEmail}</p>
    </div>
  )
}

For Remix, the Auth object is accessed using the getAuth() function. Learn more about using getAuth().

routes/profile.tsx
import { LoaderFunction, redirect } from '@remix-run/node'
import { getAuth } from '@clerk/remix/ssr.server'
import { createClerkClient } from '@clerk/remix/api.server'

export const loader: LoaderFunction = async (args) => {
  // Use `getAuth()` to retrieve the user's ID and session claims
  const { userId, sessionClaims } = await getAuth(args)

  // If there is no userId, then redirect to sign-in route
  if (!userId) {
    return redirect('/sign-in?redirect_url=' + args.request.url)
  }

  const fullName = sessionClaims.fullName

  const primaryEmail = sessionClaims.primaryEmail

  return { fullName, primaryEmail }
}

For Tanstack React Start, the Auth object is accessed using the getAuth() function. Learn more about using getAuth().

src/routes/api/example.ts
import { getAuth } from '@clerk/tanstack-react-start/server'
import { json } from '@tanstack/react-start'
import { createServerFileRoute } from '@tanstack/react-start/server'

export const ServerRoute = createServerFileRoute().methods({
  GET: async ({ request, params }) => {
    // Use `getAuth()` to retrieve the user's ID and session claims
    const { userId, sessionClaims } = await getAuth(request)

    // Protect the API route by checking if the user is signed in
    if (!userId) {
      return json({ error: 'Unauthorized' }, { status: 401 })
    }

    const fullName = sessionClaims.fullName

    const primaryEmail = sessionClaims.primaryEmail

    return 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.

  1. In your application's root folder, add a types directory.
  2. Inside of the types directory, add a globals.d.ts file.
  3. Create the CustomJwtSessionClaims interface and declare it globally.
  4. Add the custom claims to the CustomJwtSessionClaims interface.

The following example demonstrates how to add the fullName and primaryEmail claims to the CustomJwtSessionClaims interface.

types/globals.d.ts
export {}

declare global {
  interface CustomJwtSessionClaims {
    fullName?: string
    primaryEmail?: string
  }
}

Feedback

What did you think of this content?
GitHubEdit on GitHub

Last updated on