How to setup JWT token authentication for your Knowledge Base?

Protect your Crisp Knowledge Base with a JWT token when you want to restrict access to your help content. JWT tokens allow more granular authentication than a password, and are much more flexible. They however require a bit more work to implement.

Enable JWT token authentication

JWT token authentication can be enabled from your Knowledge Base settings, in the Authentication section. Whenever you enable authentication, we by default choose the "password" option. Make sure to change it to "JWT token".

When you select the JWT token option, we will auto-generate for you your JWT secret, if it is the first time you enable JWT. You will then have to provide an URL to your app where your anonymous users will be redirected by your Crisp Knowledge Base in order to authenticate them:

Once you configure the required redirection URL to your app, your Knowledge Base will become instantly protected behind an authentication wall. Your users will now have to go through your app authentication flow and get redirected back to your Knowledge Base with the signed JWT token, to get authenticated.

Authenticate users from your app

Crisp redirects anonymous users to the JWT login URL. Your authentication page will have to authorize the user, using your own proprietary authentication flow (your users might already be connected to your app), and generate a JWT token signed with the JWT private signature key we provide.

The JWT token should contain the following information:

{
  host: "help.mydomain.com",
  expire: TIMESTAMP_OF_EXPIRATION
}

The JWT token should be signed using HMAC SHA-256 (HS256). It should also contain an expiration date in the future, and the hostname of your Crisp Knowledge Base for which the signature is valid.

⚠️ Your JWT secret signature key is provided in hexadecimal form (so that you can easily copy-paste it and store it in environment variables). However, you must sign using its binary form. Please make sure to convert from hexadecimal to binary before you pass it to your JWT signing library.

You will then redirect the user to your Crisp Knowledge Base on the following URL:

https://help.mydomain.com/auth/?jwt=${JWT_TOKEN}

Crisp will then proceed validating the JWT token and storing the JWT token in a cookie so that the user stays authenticated for the lifetime of the JWT token that you generated.

Examples

JavaScript (NodeJS)

We recommend using the jose library if your signer app uses NodeJS.

Here's a sample code to sign:

import { SignJWT } from "jose";

// Get your own secret from your Crisp dashboard
const jwtSecretHex = "7a8f3bc1f6b0e88e0d46aeeb94e34fd4c1d1b6de6c6c7a4e9e58a426312387c9";

// Your secret must be converted to its binary form before use
const jwtSecret = Buffer.from(jwtSecretHex, "hex");

// Create the signed token
const token = await new SignJWT({
  host   : "help.mydomain.com",                    // Crisp Knowledge Base domain
  expire : (Date.now() + (60 * 60 * 1000)) / 1000  // 1 hour validity, in millisecs
})
  .setProtectedHeader({
    alg : "HS256"
  })
  .sign(jwtSecret);
 
// Format the redirect URL
const redirectUrl = `https://help.mydomain.com/auth/?jwt=${encodeURIComponent(token)}`;

// Then, you would redirect your user to 'redirectUrl'

Updated on: 20/09/2026

Was this article helpful?

Thank you!