Auth

You'll need to authenticate your requests to access any of the endpoints in the Chatness API. In this guide, we'll look at how authentication works. Chatness Platform offers two ways to authenticate your API requests: Org authorization and Contact authorization.

Org authorization

With the Org authorization, you will use a Bearer token containing the secret generated in your account to authenticate your HTTP requests as an organization. This method is intended to work within servers only, so you must never, in any circumstances, expose the generated secret for an organization.

import { Chatness } from '@chatness/server';

// obtain a `orgToken` from the Chatness app
const orgToken = 'your-org-token';

// obtain a `botId` from the Chatness app
const botId = 'your-bot-id';

// init the Chatness SDK
const chat = new Chatness({
  orgToken,
  botId
});

// search for contacts  
const { data } = await chat.contacts.search({
  page: 1,
  limit: 10,
  query: 'john'
});

console.log(data)

Contact authorization

In order to authorize a contact within your widget, your server should first request a session token by passing the contact id or email to the auth endpoint. Here's how to generate a session token for your contact:

  curl -X POST 'https://api.chatness.ai/v1/bots/{botId}/auth/contacts' \
       -H 'Accept: application/json' \
       -H 'Authorization: Bearer {orgToken}'
       -d id="{contactId}" \

A contact token will be generated with a validity period of 1 year. You can then pass down this token to your widget implementation and authenticate your visitors.

The generated contact token will look like the following and they can be exposed. We recommend generating a new token for each session only when needed. i.e. when users logs in your system, you can generate a new token and store it in your database, or even store locally in the browser's localStorage.

{
  "data": {
    "token": "c:f34018111f0526dd64bf8f097494f6e4",
    "createdAt": "2023-12-08T00:00:00.000Z",
    "expiresAt": "2024-12-08T00:00:00.000Z"
  }    
}

Widget authorization

Once the contact is authorized and you have a token, you can pass it down to the widget implementation and authenticate your visitors so they can start an identified conversation with your bot.

The widget can then be authenticated by your frontend:

  // received token from your server
  const token = 'c:f34018111f0526dd64bf8f097494f6e4';

  // log the user in the browser
  await window.Chatness
        .auth
        .contacts
        .login({ token })       

Revoke authorization

To revoke the authorization of a contact in the browser, you can call the public API to log out them immediately. This will ensure the session within the widget is cleared out and refreshed as anonymous.

  // log the current user out
  await window.Chatness
        .auth
        .contacts
        .logout()       

in case you're tracking the contact token in your database, you can also revoke the session from the server, this will automatically log the user out from the widget.

Attributes

Create a contact token

curl -X PUT '/v1/bots/{botId}/auth/contacts' \
  -H "Authorization: {orgToken}" \
  -d email="[email protected]"

{
  "data": {
    "token": "c:f34018111f0526dd64bf8f097494f6e4",
    "createdAt": "2023-12-08T00:00:00.000Z",
    "expiresAt": "2024-12-08T00:00:00.000Z"
  }          
}

Revoke a contact token

curl -X DELETE '/v1/bots/{botId}/auth/contacts/{contactToken}' \
  -H "Authorization: {orgToken}"