Session tokens
When a user is authenticated in your application, Clerk generates a short-lived session token that you can use to authenticate requests to your backend. This token is a JSON Web Token (JWT) that contains information about the user and their session.
Read more about Clerk session tokens and how they work in the guide on how Clerk works.
Default claims
Every generated token has default claims that cannot be overridden by templates. Clerk's default claims include:
The o claim, or organization claim, is only included if the user is part of an organization and that organization is active. Its value is an object that contains the following properties:
The act (actor) claim is only included if the user is impersonating another user. It's value is an object that contains the following properties:
Every generated token has default claims that cannot be overridden by templates. Clerk's default claims include:
The following claims are only included if the user is part of an organization and that organization is active:
The act (actor) claim is only included if the user is impersonating another user. It's value is an object that contains the following properties:
If you would like to add custom claims to your session token, you can customize it.
You can also create custom tokens using a JWT template.
Size limitations
The Clerk session token is stored in a cookie. All modern browsers limit the maximum size of a cookie to 4kb. Exceeding this limit can have adverse effects, including a possible infinite redirect loop for users who exceed this size in Next.js applications.
A session token with the default session claims won't run into this issue, as this configuration produces a cookie significantly smaller than 4kb. However, this limitation becomes relevant when implementing a custom session token. In this case, it's recommended to move particularly large claims out of the token and fetch these using a separate API call from your backend.
Claims to monitor for size limits:
user.organizationsuser.public_metadatauser.unsafe_metadataorg.public_metadataorg_membership.public_metadata
If you include any of these claims in your token, use caution to ensure the stored data doesn't exceed the size limit.
Validate session tokens
If you're using the middleware provided by our Clerk SDKs, validating session tokens is handled automatically in every request. If you're not using the middleware, you can still use the respective helpers provided by the SDKs to validate the tokens.
To learn how to manually verify a session token, refer to the dedicated guide.
Feedback
Last updated on