Kindly Chat authentication

Kindly supports authenticating your users. When your users are authenticated, it's easier to identify them in the Kindly Inbox and you can create more personalized and powerful webhook integrations.

To set this up you need to do a few things:

• Add a callback to Kindly Chat initialization code.
• Create a private/public key pair.
• Create an authentication endpoint that returns a JWT in a specific format.

After the inital implementation and setup you are able to:

• See user details in the Kindly Inbox.
• Identify users in webhooks (via the forwarded JWT).

The chat client embeded on your site needs to know where your authentication endpoint is, it is responsible for calling that endpoint and feeding the token to Kindly. You need to define a callback function on window.kindlySettings.getAuthToken, like the example below, which must return the JWT token. The function is called with a single argument chatId which identifies the current chat. If you are lucky enough to have the token available in memory already, the callback could be made even simpler.

Example initialization code with callback using the browser fetch API:

To allow your own server to authenticate webhook requests without the Kindly API interfering, we use a standard private/public key pair.

The private key is used by your server to encode and sign the JWT in your authentication endpoint.

Add your public key to your bot under Settings -> Kindly Chat -> Authentication. The public key is used by the API to verify that the JWT is valid.

Run the following commands to generate a key pair.

The contents of private.pem should look something like:

and the contents of public.pem should look like this:

The responsibility of authenticating your users is yours and is done by an HTTP endpoint you implement. In the most common case, the Kindly Chat callback sends a HTTP POST request to an authentication endpoint you implement. If the Kindly Chat JavaScript request is sent from the same domain as the endpoint, CORS headers can be omitted.

Create an authentication endpoint that returns a JWT in the format specified below. Be aware that JWTs are encoded and signed, not encrypted, meaning anyone who has the token can read the content.

Set up an authentication endpoint on your backend that returns a JSON Web Token (JWT) signed using the RS256 algorithm and the private key created in the step above, and the payload must conform to the following required format:

You can implement the auth endpoint however you wish. We recommend using a compatible JWT library from the list at https://jwt.io/.

You may also include any other property you want to use in your webhooks. You can read more on JWT in the standard here.

Once the authentication setup is done, a JWT token from your authentication endpoint is passed to the Kindly API which can send the token to a webhook you specify (using advanced replies). When a webhook contains a token it can be used to identify a user and provide support for a wide range of integration use cases.

You'll find the JWT token in the standard Authorization header, ie. Authorization: Bearer <JWT>. Remember, you can use the debug console to inspect webhook request and responses, including their headers.

To prevent leaking tokens to unwanted third parties, the webhook domains a JWT token can be forwared to must be encoded in the token. Thus the tokens will not automatically be sent from Kindly to all webhooks in a bot. This also implies that the domains must be known in advance. See the section about token format for more info.

To be able to act on behalf of the user in a webhook request, you first need to verify the JWT token, using the public key you generated earlier. After you have done that, you can extract information from it and be sure of its authenticity.

Note that Kindly also verifies the JWT using the public key you provide to us. The public key can be found under Settings -> Kindly Chat -> Authentication for your bot.