Authentication

Authentication

All API calls are authenticated with the combination of two separate keys: API Key and API Secret.

The API Key is the public key and can be put in clear client-side (your website, your app...). The API Secret should never be shared publicly and should only be set on your server.

There are two different modes of authentication for Studio endpoints: Private or Public.

Public Endpoints Authentication

Public Endpoints (consisting of Chat and Broadcasts API endpoints) can be authentified by providing only the value of the Api Key in the X-Api-Key header. They can be accessed from the frontend, i.e by creating your own chat interface integrated in your app or website.

Implementation examples

When calling Chat and Broadcasts API endpoints, you only need to set the X-Api-Key header as follows:

curl -X "POST" "https://API_ENDPOINT" \
     -H 'content-type: application/json' \
     -H 'X-Api-Key: YOUR_API_KEY' \
     -d $'YOUR_REQUEST_BODY'

Private Endpoints Authentication

Private Endpoints are endpoints that should only be accessible to the developer of the chabot, allowing to modify the chatbot in its entirety or access conversation data (Bot and Conversations API endpoints). To authentify your Private Endpoints requests you need to set the X-Api-Key and X-Api-Signature headers. The CSML Studio Private APIs use HMAC authentication to ensure that all calls are properly signed with both the API Key and API Secret, while preventing man-in-the-middle attacks and replay attacks

The X-Api-Signature process MUST NEVER be done on the client side, as this would let any person in control of your API Secret also control your bot (make changes, get user data...). Obviously, never share your API Secret with anyone in clear text.

In the X-Api-Key header, concatenate the API Key and the current unix timestamp (in seconds), separated by the | character. In the X-Api-Signature header, provide the hexadecimal sha-256 hash of the X-Api-Key header value, signed with your API Secret.

The CSML server will be able to validate that both the API Key and the API Secret used are valid, without requiring you to provide the API Secret in clear text. Replay attacks are prevented by invalidating all calls a few minutes after the timestamp provided in the X-Api-Key header.

Implementation examples

To authenticate your Private calls, you need to calculate the signature based on the Api Key and the Api Secret that you can find in CSML Studio, as well as the current timestamp. Here are implementation examples of the X-Api-Key and X-Api-Signature headers in Node.js and Python.

NB: this calculation should never be performed client-side!

Node.js

const crypto = require('crypto');

const UNIX_TIMESTAMP = Math.floor(Date.now() / 1000);

const XApiKey = `${API_KEY}|${UNIX_TIMESTAMP}`;
const signature = crypto.createHmac('sha256', secret)
  .update(XApiKey, 'utf-8')
  .digest('hex');
const XApiSignature = `sha256=${signature}`;

Python

import time
import hmac
import hashlib

timestamp = str(int(time.time()))
x_api_key = ${API_KEY} + "|" + timestamp

signature = hmac.new(
    str.encode(${API_SECRET}),
    x_api_key.encode('utf8'),
    digestmod=hashlib.sha256
  ).hexdigest()
x_api_signature = "sha256=" + signature

Then, perform an authenticated call as follows:

curl -X "POST" "https://API_ENDPOINT" \
     -H 'content-type: application/json' \
     -H 'X-Api-Key: YOUR_API_KEY_AND_TIMESTAMP' \
     -H 'X-Api-Signature: YOUR_CALCULATED_API_SIGNATURE' \
     -d $'YOUR_REQUEST_BODY'