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.

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(opens in a new tab). See RFC 7519(opens in a new tab) for more information.
iat: issued at - the time at which the token was issued as a Unix timestamp. For example: 1516239022. See RFC 7519(opens in a new tab) 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(opens in a new tab) 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(opens in a new tab). See RFC 7519(opens in a new tab) for more information.
sid: session ID - the ID of the current session (e.g. sess_123).
sub: subject - the ID of the current user of the session (e.g. user_123). See RFC 7519(opens in a new tab) for more information.
act: actor - will only be included if the user is impersonating another user. See user impersonation for more information.

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.

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, please refer to the dedicated guide.

Last updated on April 8, 2024