Obtaining API Authorization

Obtaining access

Log in to the elven system, navigate to the entity where api access is required, go to the journals page, and click on the integrations button in the top right corner of the journals page.

In the pop-up integrations management window, click the “add new integration” button.

Name the new data type and click the “add” button.

Once the data type is added, you can add new data. click the “add data” button and select “openapi integration” from the drop-down menu.

In the api key/secret management window that pops up, click the “create” button.

In the next window, name the newly created api key.

Click the “create” button to complete the creation of the new api key. You can click the copy icon next to each key/secret to copy the contents to your clipboard for use.

Using api access

Provide the following parameters in the request header:

elven-api-key: obtained api key
elven-api-sign: base64-encoded signature, e.g., LVT5aXA9064gpgZrPXPLJB/Aq9r45yMF10sTZQTteyE=
elven-api-timestamp: timestamp in milliseconds, e.g., 1721209655047, expires after 30 seconds

The sign algorithm as follows: concatenate the timestamp, request method, and request route, then encrypt using hmac sha256 with the secret.

// uses the crypto library from https://github.com/nodejs/node/blob/v16.9.0/lib/crypto.js
/**
 * generate signature
 * apiSecret: BjGiqCWfHGCrl065dlEBWFO5vLj7Hqiexxx,
 * timestamp: 1721205912758
 * method: POST
 * path: /open/v3/businessData
 */
buildSign(apiSecret: string, timestamp: number, method: string, path: string) {
  const str = `${timestamp}${method}${path}`
  return crypto.createHmac('sha256', apiSecret).update(str).digest('base64')
}

Example:

// example parameters
[
  'D7JLJ3awwrTdNXtSrPI1GlYE', // key
  'BjGiqCWfHGCrl065dlEBWFO5vLj7Hqie', // secret
  'POST', // method, must be uppercase
  '/open/v3/businessData' // path, must start with '/'
]

// headers
{
  'elven-api-key': 'D7JLJ3awwrTdNXtSrPI1GlYE',
  'elven-api-sign': 'LVT5aXA9064gpgZrPXPLJB/Aq9r45yMF10sTZQTteyE=',
  'elven-api-timestamp': 1721209655047
}