Medici Bank API
Medici Bank API

Making Requests

To secure all requests, we require all requests to include a specific set of HEADERS.


MBAPI-KEY Your unique PUBLIC API key
MBAPI-TIMESTAMP The user generated timestamp for the request. Must be number of seconds since Unix Epoch
MBAPI-SIGNATURE The user generated message signature. The MBAPI-SIGNATURE header is generated by creating a SHA512 HMAC message digest with base64 encoding, using your MBAPI-SECRET as the secret key. See below for an example of how to construct the HMAC signed request
MBAPI-NONCE A unique string that identifies this request and prevents the replaying of a past request. Please see below on how to construct this nonce
Authorization Bearer: MBAPI-AUTHTOKEN

Please note: For POST requests, you should JSON.stringify the body to avoid a mismatch in formatting for the signed request.


In cryptography, an HMAC (sometimes expanded as either keyed-hash message authentication code or hash-based message authentication code) is a specific type of message authentication code (MAC) involving a cryptographic hash function and a secret cryptographic key. HMAC - Wikipedia

In regular terms, HMAC is the process of using a key, in this case, your MBAPI-SECRET, and encrypting a concatenated string version of your entire API request. By encrypting the entire request, we can not only hide the contents of that request, but we can also ensure that all information can only be decrypted by those who have key permissions to do so.

Signing your API request is straightforward. Below is an example of how to do so:

HMAC Signed Request

Node.js Example

var hash = crypto.createHmac(‘sha512’, {Your MBAPI SECRET}); // your MBAPI-SECRET e.g. “dONgcyGwBVupn/U2y8AdONGWkjfGomJqiKXk2BYaK4sd”

hash.update("Your MBAPI Key"); // your MBAPI-KEY e.g. "361b4140-0607-11ea-8bff-5fcd0b2b8452"
hash.update("API Request Method"); // e.g. GET
hash.update("API Path/URL"); // encoded API request URL e.g. ""
hash.update("Unix Timestamp"); // e.g. "1574184580246"
hash.update("JSON.stringify(API Request Body)"); // your request body

var hmacSignedRequest = hash.digest('base64');


A Nonce is a number or string, that can be used only once. The reason for using a nonce in API requests, is to ensure that once a request has been sent, regardless of whether that request is successful, it still cannot be used (or resent) again. This guards against Replay Attacks and some Man-in-the-Middle Attacks.

There are a number of ways to create a nonce. However, we ask that you create this nonce in a specific way. The MBAPI-NONCE should be constructed using your MBAPI-KEY + MBAPI-TIMESTAMP + A random 32-character string. Then taking that string and creating a base64_encoded hash. Very similar to the process of creating your HMAC signed request.

Below is an example of how to do so:


Node.js Example

var hash = crypto.createHash(‘sha512’);

hash.update("Your MBAPI-KEY");
hash.update("Your MBAPI-TIMESTAMP");
hash.update("Your Random 32 Character String");

var MBAPI-NONCE = hash.digest('base64');


All API requests must be made over secured HTTPS. Any call made over a plain HTTP connection will fail automatically and a 400 none_https error response will be returned.

Next, we will take a look at the standard definitions and data structures we enforce…

Medici Bank International © 2019. All Rights Reserved.