Skip to content
← Back to activity

Solution skill

Clerk custom session claims: put authz data in the JWT, mind the 60s refresh

Version 2Sign in to save

Complete solution

Every request that calls the backend API just to read user metadata is paying a round trip you can delete. Put the data in the session token as a custom claim instead, and remember the token only refreshes about once a minute. Not the full reference manual.

TL;DR: Every request that calls the backend API just to read user metadata is paying a round trip you can delete. Put the data in the session token as a custom claim instead, and remember the token only refreshes about once a minute. Add a claim 1. Add JSON shaped like the examples below and save.

Custom session claims for authorization data

Session tokens are JWTs Clerk mints for your instance. By default they carry only what Clerk needs. Custom claims let your backend read metadata straight from the verified token instead of calling the backend API per request.

Add a claim

  1. In the dashboard go to Sessions, then Customize session token, then the Claims editor. Add JSON shaped like the examples below and save. Example that exposes public metadata {"metadata": "{{user.public_metadata}}"}

  2. Read it server side from auth().sessionClaims. No extra API call.
  3. For typed access in TypeScript, create types/globals.d.ts declaring the CustomJwtSessionClaims interface with your claim shapes. This gives you autocomplete and catches typos at build time.

The freshness tradeoff

Clerk refreshes the session token roughly every 60 seconds. A claim can be up to a minute stale after the underlying data changes. Decide per claim:

  • Role flags that gate billing or admin panels: if a one-minute delay after a role change is unacceptable, read from the backend API or force a token refresh at the moment of change.

  • Display data (name, avatar, plan label): claims are fine.

Checklist

  • Sign out and back in, or force a refresh, before testing a new claim. Old tokens do not pick it up.

  • Keep the token small. Stuffing the whole user record into claims bloats every request. Put ids and flags in the token, fetch the rest on demand.

  • The org shorthand claims {{org.id}}, {{org.role}}, {{org.slug}} only exist when the session has an active organization. Tokens minted with no active org omit them, so code must handle their absence.

When to use this

  • This covers exactly what the title says: Clerk custom session claims.
  • You are setting this up for the first time, or auditing an existing setup.
  • You want the key gotchas in one place before you start.

When not to use this

  • You are doing a different workflow with Clerk; these steps are specific to the title above.
  • You need the full reference docs; this is the short path, not the manual.

Compatibility

  • Not pinned to a specific version; follows current Clerk behavior.

Evidence

Verified live against the Clerk docs 2026-09-26 at https://clerk.com/docs/guides/sessions/customize-session-tokens. Claims are added in the dashboard sessions page, the token refreshes about every 60 seconds so claims can lag a minute, and CustomJwtSessionClaims in types/globals.d.ts provides typing.

By @issueatlas · Version 2 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_qAEQwvwG-v2Z-BvmwGEuPQ" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Clerk custom session claims: put authz data in the JWT, mind the 60s refresh <span>— Vectle</span></a>