Asset issuance API

0.0.2

This is draft documentation for Bitbond tokenisation API.

Authorization

API clients are authorized with bearer tokens. Tokens can be generated in the admin panel as a key/secret pair. Secret are used to build HMAC-SHA1 signatures on a client side.

Signature generation pseudo code

/**
 * HMAC a hashing function using SHA1 algorythm
 * @param   {String} secret     The secret used to hash the message
 * @param   {String} message    Message to be hashed
 * @return  {Bin}               Binary digest
 */
HMAC = func(secret, message)

/**
 * signatureKey returns derived key
 * @param   {String} secret     The secret from tokens key/secret pair.
 * @param   {String} date       UTC request date in YYYY-MM-DD format
 * @param   {String} method     Request method POST, GET, DELETE etc
 * @param   {String} path       Request path, e.g. /api/v1/access_tokens
 * @return  {Bin}               Derived key used to generate payload signature
 */
signatureKey = func(secret, date, method, path) {
    HMAC(HMAC(HMAC("bitbond" + secret, date), method), path)
}

/**
 * signature returns request signature
 * @param   {String} key        The secret from tokens key/secret pair.
 * @param   {String} payload    Raw request body
 * @return  {String}            Request signature
 */
signature = func(key, payload) {
    HMAC(key, payload).toString()
}

Example in JavaScript

import hmacSHA1 from 'crypto-js/hmac-sha1';

let generateSigningKey = (secret, dateStamp, method, path) => {
  let key = hmacSHA1(dateStamp, `bitbond${secret}`)
  key = hmac(method, key)
  key = hmac(path, key)
  return key
}

let dateStamp = (new Date()).toISOString().substring(0, 10)
let method = request.method
let path = request.url.getPath()
let body = request.body && request.body.raw || ''
let signingKey = generateSigningKey(secret, dateStamp, method, path)
let signature = hmacSHA1(body, signingKey).toString()

Headers

To authorize API access this header needs to be added to the request.

Authorization: Bearer [token]
X-Signature: Request signature

This is version 0.0.2 of this API documentation. Last update on Apr 21, 2021.