Search…
Validating session tokens
A guide to manually validate your session tokens

Introduction

When a user is authenticated in your application, a short-lived session token is generated by Clerk.js that depicts the fact and it's sent to your backend. Your backend will typically want to validate that the session token is valid (i.e. that it comes from Clerk, that it hasn't expired etc.)
If you're using the middlewares provided by our Clerk SDKs, this is all handled automatically in every request. If you're not using the middlewares, you can still use the respective helpers provided by the SDKs to validate the tokens. That is all good, but if an SDK does not exist for application's programming language, you will have to manually validate these tokens.
This guide provides instructions on how to do exactly that; manually validate the Clerk session tokens that your backend receives.

Overview

Your Clerk-generated session tokens are essentially JWTs which are signed using your instance's private key and can be verified using your instance's public key. Depending on your architecture, these tokens will be in your backend requests either via a cookie named __session or via the Authorization header.
For every request, you must validate its token to make sure it hasn't expired and it is authentic (i.e. no malicious user tried to tamper it). If these validations pass, then it means that the user is authenticated to your application and you should consider them signed in.

Instructions

By following the steps below, you can validate the session token on your own and make sure that the user session is still active and valid.
  1. 1.
    Retrieve the session token from either __session cookie or from the Authorization header
  2. 2.
    Get your instance's Public Key. There are 3 ways to do it:
    1. 1.
      Via the Backend API in JSON Web Key Set (JWKS) format at the following endpoint https://api.clerk.dev/v1/jwks
      (If there is more than one JWKS, decode your session token, get the token kid from the header part and construct the respective public key)
    2. 2.
      Via the Frontend API in JSON Web Key Set (JWKS) format at the following endpoint https://<YOUR_FRONTEND_API>/.well-known/jwks.json
      (If there is more than one JWKS, decode your session token, get the token kid from the header part and construct the respective public key)
    3. 3.
      If you are planning to use Clerk on a Serverless/Edge Runtime where JWKs caching is challenging, you can use the instance Public Key as an environment variable. The key can be found in Dashboard > Settings > API Keys > JWT Verification Key. Note that the JWT Verification key is not in PEM format, the header and footer are missing, in order to be shorter and single-line for easier setup.
  3. 3.
    Use the above Public Key to verify the token's signature
  4. 4.
    Validate that the token is not expired, by checking the exp and nbf claims
Steps (3) and (4) should better be done by existing JWT libraries of your favourite language
If the above process is successful, it means that the user is signed in to your application and you can consider him authenticated. You can also retrieve the session ID and user ID out of the token's claims.
Last modified 3d ago
Copy link
Edit on GitHub