Avoid repeated Backend API lookups
A backend repeatedly needs a small set of user attributes and can tolerate token refresh latency.
Clerk · Pipe
sessionClaims
sessionClaims exposes claims from the current Clerk session token through the Auth object. Configure custom claims in Clerk's session-token editor, then read them with the authentication API for your SDK.
How it works
The Auth object exposes sessionClaims, containing claims from the current user's Clerk session token. Add custom claims in the Clerk Dashboard's session-token Claims editor, then read them through the authentication API appropriate to the SDK; token values can lag behind source data until the next refresh.
Syntax
const { sessionClaims } = await auth()Returns
The current user's session claims, exposed as the sessionClaims property of the Auth object; the Auth reference types it as JwtPayload.
Key points
- Clerk issues session tokens as JWTs that convey an authenticated user session to the backend.
- Embedding needed values as custom claims avoids a separate Backend API request for each access.
- Use the Claims editor to define the fields that should be included in the token.
- The access method depends on the Clerk SDK and framework; consult the matching SDK reference.
- In Go, obtain claims from the request context with SessionClaimsFromContext().
Common mistakes
- Custom claims are not immediately fresh: allow for up to about 60 seconds, or retrieve current data from the Backend API when an immediate update matters.
- Keep the complete session token small because it is stored in a cookie; the documented practical allowance for custom claims is about 1.2KB after default claims.
- The property contains claims configured in the session token, so configure the desired fields before attempting to read them.
Example: Read session claims in Next.js
import { auth } from '@clerk/nextjs/server'
export default async function Page() {
const { userId, sessionClaims } = await auth()
if (!userId) return <p>Sign in required</p>
return <pre>{JSON.stringify(sessionClaims, null, 2)}</pre>
}This server component reads the authenticated user's session claims through Clerk's auth helper.
When to use it
Read custom authorization data
An application needs to make authorization or display decisions using compact role or profile data included in the session token.
Access claims from Go request context
A Go HTTP handler needs verified claims from Clerk middleware.
Interview questions
QWhat is sessionClaims in Clerk, and how do you populate it?
sessionClaims is a property of Clerk's Auth object and represents the current user's session claims. Custom claims are placed into the session token through the Clerk Dashboard's Claims editor and can then be read with the SDK-specific authentication API.
Follow-up: Why might a newly changed claim not appear immediately? The session token refreshes every 60 seconds, so use the Backend API or force a token refresh when immediate consistency is required.
QWhy use custom session claims?
Custom claims let the application receive selected user data with the session token instead of making a Backend API request for every read. This can reduce round trips, but the data may be briefly stale.
Follow-up: When should the Backend API be preferred? Use it when the change must be visible immediately or when the required data should not be carried in the token.
QWhat size constraint applies to session claims?
Clerk stores the session token in a browser cookie, and browsers commonly cap cookies at 4KB. After default claims are included, Clerk documents roughly 1.2KB as available for custom claims.
Follow-up: What design consequence follows? Include only compact, frequently needed fields and avoid placing large objects in the token.
Related
Auth objectauth()useAuth()SessionClaimsFromContext()custom session tokensession tokens