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