API Reference

Authentication & Authorisation

Types of Endpoint

CIS Portfolio Analytics provides endpoints that are split into the following two use cases:

  • Explicitly for the tenant to use to manage & monitor the system
  • For the tenant's user base to access relevant data there linked accounts & portfolios

Authentication requires calls be made with either

Tenant Endpoints:

  • a JWT token for a user that has been setup as an admin user for the tenant
  • an API Key & Signature (generated from the corresponding API Private Key / Secret) - The API Key & Secret must have been generated for the tenant and given the relevant claims / access

Tenant User Endpoints

  • A JWT Token generated for the tenant user - Tokens can be generated by tenants for their users using the SessionToken/Create endpoint
  • An API Key & Signature (generated from the Private Key / Secret) - The API Key and secret must have been generated for the user and given the relevant claims / access

Authentication with an API Key & Secret

When making calls to endpoints using an API Key the following must be provided to authenticate the request

X-API-KEY header containing the API Key
X-API-TIMESTAMP header containing the current, UTC UNIX timestamp
X-API-SIGNATURE header containing a HMAC SHA256 signature generated from the timestamp and the API private Key / Secret

Signature Generation

The signature should be generated using the current, UTC UNIX timestamp and the API private Key / Secret. The following javascript code shows how to generate this using the CryptoJS node.js package CryptoJS

const apiSecret = "2028c72a-2bd3-4b0d-9e0e-1c9b5d4274df";
const timestamp = 1625609684
let query = 'timestamp=' + timestamp
const sign = CryptoJS.HmacSHA256(query, apiSecret).toString(CryptoJS.enc.Hex);
console.log(sign)
>> bccfa3ff9fbdfaf48426d689dcaa23b5874ffbbf17acfa887036ff5d26461831
  • The timestamp must be a UTC, UNIX timestamp to seconds precision
  • The timestamp should be prefixed with the string 'timestamp=' - the resulting string should be used to generate the signature.
  • If a request is received and the signature generated is for a timestamp that is older than 60 seconds (or 60 seconds in the future) - the request will be rejected

Please Note - If you want to add a pre-request script for a postman collection that handles the siganture then you can use the below script (replace my_api_key & my_api_secret with your own) 

const apiKey = "my_api_key";
const apiSecret = "my_api_secret";
const timestamp = Math.floor(new Date().getTime()/1000);
let query = 'timestamp=' + timestamp
const signature = CryptoJS.HmacSHA256(query, apiSecret).toString(CryptoJS.enc.Hex);
console.log(signature,timestamp);

pm.request.headers.add({key: 'X-API-KEY', value: apiKey });
pm.request.headers.add({key: 'X-API-TIMESTAMP', value: timestamp });
pm.request.headers.add({key: 'X-API-SIGNATURE', value: signature });

❗️

API Key / Secret Security

  • Do not share your API Key / Secret with anyone.
  • NEVER expose your private key / secret in client side code or code repository's

If you believe the API Key & Secret may have been exposed or compromised you should regenerate them immediately.