Session token customization

Session tokens are JWTs generated by Clerk on behalf of your instance, and convey an authenticated user session to your backend.

They typically contain a standard set of claims that are required for Clerk to function. However, there may be times when you want to include additional claims in those tokens.

By leveraging JWT Templates you can include additional claims in your instance's session tokens.

This guide assumes familiarity with session tokens and JWT templates.

Customization of session tokens essentially means augmenting them with additional JWT claims of your choice.

Note that all session tokens contain a set of standard claims, which are set automatically by Clerk and are essential for it to function. These claims cannot be customized and currently are the following:

* The orgs claim will no longer be set in the session token for applications created after 2022-08-11 and will eventually be phased out ever for older apps. If you wish to add orgs, please use the user.organizations claim in your custom session token JWT template.

Apart from those, you can customize your session tokens to include any custom claims, by navigating to Settings → Sessions and clicking the Edit button inside the Customize session token card.

That's it! After you set your claims, all subsequent session tokens generated by your instance will contain the additional claims, as specified in your JWT template.

If you encounter any issues or have question and feedback, please contact us: