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

Clerk stores the session token in a cookie, and most browsers cap cookie size at 4KB. After accounting for the size of Clerk's default claims, the cookie can support up to 1.2KB of custom claims. Exceeding this limit will cause the cookie to not be set, which will break your app as Clerk depends on cookies to work properly. 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 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 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 access `isAuthenticated` and 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. .

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

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

  // Protect the route by checking if the user is signed in
  if (!isAuthenticated) {
    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. .

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 Go, the session claims are accessed using the SessionClaimsFromContext() function.

main.go
package main

import (
  "context"
  "fmt"
  "net/http"

  "github.com/clerk/clerk-sdk-go/v2"
  clerkhttp "github.com/clerk/clerk-sdk-go/v2/http"
  "github.com/clerk/clerk-sdk-go/v2/user"
)

type CustomSessionClaims struct {
   FullName string  `json:"fullName"`
   PrimaryEmail string `json:"primaryEmail"`
}

func customClaimsConstructor(ctx context.Context) any {
   return &CustomSessionClaims{}
}

func WithCustomClaimsConstructor(params *clerkHttp.AuthorizationParams) error {
   params.VerifyParams.CustomClaimsConstructor = customClaimsConstructor
   return nil
}

func main() {
  clerk.SetKey("YOUR_SECRET_KEY")

  mux := http.NewServeMux()
  protectedHandler := http.HandlerFunc(protectedRoute)
  mux.Handle(
    "/protected",
    clerkhttp.WithHeaderAuthorization(WithCustomClaimsConstructor)(protectedHandler),
  )

  http.ListenAndServe(":3000", mux)
}

func protectedRoute(w http.ResponseWriter, r *http.Request) {
  // Protect the route by checking if the session claims are present
  claims, ok := clerk.SessionClaimsFromContext(r.Context())
  if !ok {
    w.WriteHeader(http.StatusUnauthorized)
    w.Write([]byte(`{"access": "unauthorized"}`))
    return
  }

  // Access the custom claims
 customClaims, ok := claims.Custom.(*CustomSessionClaims)
  if !ok {
    // Handle the error how you see fit
  } else {
    fmt.Fprintf(w, `{"full_name": "%s", "primary_email": "%s"}`, customClaims.FullName, customClaims.PrimaryEmail)
  }
}

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

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

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

  // Protect the route by checking if the user is signed in
  if (!isAuthenticated) {
    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. .

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 access `isAuthenticated` and the user's ID and session claims
  const { isAuthenticated, userId, sessionClaims } = await getAuth(args)

  // Protect the route by checking if the user is signed in
  if (!isAuthenticated) {
    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. .

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 access `isAuthenticated` and the user's ID and session claims
    const { isAuthenticated, userId, sessionClaims } = await getAuth(request)

    // Protect the API route by checking if the user is signed in
    if (!isAuthenticated) {
      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