Chatbot JWT authentication

When using the AI chatbot with private knowledge bases, or knowledge bases with a mix of public and private content, JWT authentication can be used to control access.

With JWT authentication, you'll need:

1. A JWT client secret to retrieve the token.
2. To update your chatbot embed script to pass in the JWT token to authenticate and display the chatbot to your readers.

Get your client secret

First,  generate the JWT Client Secret for your knowledge base:

1. Go to KB settings > AI Chatbot.
2. In the External website embed section, check the JWT authentication checkbox and click the Copy button. If no secret is displayed, click on the Generate JWT secret button to generate one.

Now that you have your client secret, go the the Embed code section and copy the JWT authentication embed code. The provided code includes 2 examples of how to use, choose the one that best fits your application workflow.

Working with JWT authentication

For information about what JWT is and how you can use it, refer to this JWT introduction article. For use with our contextual help widget, use the following requirements:

JWT header

Your JWT header must specify the HS256 encryption algorithm:

// Encryption algorithm must be HS256
{
  "alg": "HS256",
  "typ": "JWT"
}

JWT payload

Your JWT payload must include these fields and values:

{
  "iss": "https://app.knowledgeowl.com", // Issuer - *required
  "aud": "https://YOUR.KNOWLEDGEBASE.URL", // Audience - *required
  "service": "chatbot",
  "scope": "chatbot:interact",
  "iat" => unixTimestamp, // Issued At - *required
  "nbf" => unixTimestamp - 1000, // Not Before - *required
  "exp" => unixTimestamp + 1000, // Expires - *required
  "reader": {
    "ssoid": endUserUID, // Unique ID - *required,
    "username": endUserEmail, // Email or Username - *required,
    "groups": "Support,Admin" // Comma separated list of reader group names - optional
  }
}