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.

Learn more about how Clerk combines session token authentication and JWT authentication in the blog post⁠.

Default session claims

Every generated token has default claims that cannot be overridden by templates. Clerk's default claims include:

• azp: authorized party - the Origin header that was included in the original Frontend API request made from the user. Most commonly, it will be the URL of the application. For example: https://example.com. This claim could be omitted if, for privacy-related reasons, Origin is empty or null.
• exp: expiration time - the time after which the token will expire, as a Unix timestamp. Determined using the Token lifetime JWT template setting in the Clerk Dashboard⁠. See RFC 7519⁠ for more information.
• iat: issued at - the time at which the token was issued as a Unix timestamp. For example: 1516239022. See RFC 7519⁠ for more information.
• iss: issuer - the Frontend API URL of your instance. For example: https://clerk.your-site.com for a production instance or https://your-site.clerk.accounts.dev for a development instance. See RFC 7519⁠ for more information.
• nbf: not before - the time before which the token is considered invalid, as a Unix timestamp. Determined using the Allowed Clock Skew JWT template setting in the Clerk Dashboard⁠. See RFC 7519⁠ for more information.
• sid: session ID - the ID of the current session For example: sess_123.
• sub: subject - the ID of the current user of the session. For example: user_123. See RFC 7519⁠ for more information.
• act: actor - will only be included if the user is impersonating another user. It's an object that contains the following properties:
  • iss: issuer - the referrer of the token. For example: https://dashboard.clerk.com.
  • sid: session ID - the session ID of the impersonated session. For example: sess_456.
  • sub: subject - the ID of the impersonator. For example: user_456.

The following claims are only included if the user is part of an organization:

• org_id: organization ID - the ID of the active organization that the user belongs to.
• org_permissions: organization permissions - the permissions of the user in the currently active organization.
• org_slug: organization slug - the slug of the currently active organization that the user belongs to.
• org_role: organization role - the role of the user in the currently active organization.

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.organizations
• user.public_metadata
• user.unsafe_metadata
• org.public_metadata
• org_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, this is all 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.