Authentication V2

This section is critical, authentication is REQUIRED for accessing every open APIs.

Create API Key

1. Navigate to CRM Back Office - Settings - Dev Space - Open API Keys Page
2. Create an API Key

Note:

API Key will only display one time after creation. Please copy and save your API Key into a secure location. If you lose your API key, please delete and create another.

Warning

For data security, please ensure that the API key is kept safely.

Key Authentication

Requesting every API in this documentation requires authentication via the above API key. Please attach the API key as a http header of the request.

HTTP Header	value
key	API Key created from CRM

Signature

Any POST/PATCH/PUT API that contains a request body will need to sign the request and provide the signature as a HTTP header.

HTTP Header	value
signature	calculated using the algorithm below

Signature Algorithm

1. Calculate a hash using your SECRET_TOKEN, and ensure that the result matches the hash from CRM. CRM uses an HMAC hex digest to compute the hash.

Note

If your language and server implementation specifies a character encoding, ensure that you handle the payload as UTF-8.

Sample JavaScript code to obtain the signature

Ruby

def generate_signature(payload_body)
  signature = 'sha256=' + OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), ENV['API_KEY'], payload_body)
  return signature
end

PHP

<?php
    use Psr\Http\Message\RequestInterface;
    
    function generate_signature(RequestInterface $req) {
        $API_KEY = getenv('API_KEY');
        $signature = hash_hmac('sha256', json_encode($req->getBody()), $API_KEY);
        $trusted = 'sha256=' . $signature;
        return $trusted;
    }
?>

Python

import hashlib
import hmac
def generate_signature(payload_body, api_key):
    hash_object = hmac.new(api_key.encode('utf-8'), msg=payload_body, digestmod=hashlib.sha256)
    expected_signature = "sha256=" + hash_object.hexdigest()
    return expected_signature

Javascript

let encoder = new TextEncoder();

async function generateSignature(api_key, payload) {
	const trusted_signature = crypto
	    .createHmac('sha256', key)
	    .update(JSON.stringify(payload))
	    .digest('hex');
	const trusted = Buffer.from(`sha256=${trusted_signature}`, 'ascii');
	return trusted;
}

Typescript

import * as crypto from "crypto";

const API_KEY: string = process.env.API_KEY;

const generateSignature = (req: Request) => {
  const signature = crypto
    .createHmac("sha256", API_KEY)
    .update(JSON.stringify(req.body))
    .digest("hex");
  let trusted = Buffer.from(`sha256=${signature}`, 'ascii');
  return trusted;
};

Error Codes

HTTP Code	Error Type	Description
403	invalid_api_key	API key is not exist or invalid
403	invalid_signature	Signature does not match