API Key Authentication

Secure authentication

To secure our API, we use a robust authentication protocol.

Required Headers

Most Noba API calls require the following headers to be provided:

  • X-Noba-API-Key: API key provided to you by Noba
  • X-Noba-Signature: Signature computed using the algorithm explained below
  • X-Noba-Timestamp: Current timestamp when request is sent

Signature Computation

The signature must be computed using the algorithm described below or the call will fail.

  1. Concatenate the following values:
  • Timestamp - this is the same value as the X-Noba-Timestamp header and can be 0 for testing
  • API Key - this is the same value as the X-Noba-API-Key header
  • Request method - method of the request (e.g. GET, POST, PATCH, DELETE)
  • Request path - Path of the API call, omitting the server component (e.g. /v1/countries). Note that any path params must also be encoded into this value (e.g. /v1/countries/US)
  • Body content - The full JSON payload sent in the request (typically only used for POST requests)
  1. Generate a HMAC using SHA256 with the string created above and secret key provided to you by Noba.
  2. Convert the HMAC to a Hex string.

To assist with creating this signature in test environments, use the Javascript tool below as follows:

  1. Save this code to a file called computesignature.js
  2. Set environment variables for NOBA_API_KEY and NOBA_API_SECRET using the values provided to you by Noba.
  3. Execute the program using node with the following syntax: node computesignature method path [body]
    This will return the signature to provide in the X-Noba-Signature header when using the API key provided and a value of 0 for X-Noba-Timestamp.

:warning: Using the body parameter in this script is still not 100% fleshed out. If making Post calls, it would be best to integrate the createHeaderSignature() function into your own program.

const cryptoJS = require("crypto-js");
const {EOL} = require('os');

if (!process.env.NOBA_API_KEY  ||
    !process.env.NOBA_API_SECRET  ||
    process.argv.length < 4) {
    console.error("Usage: node computesignature method path [body]");
    console.error("Environment variables for NOBA_API_KEY and NOBA_API_SECRET must also be set");

const args = process.argv.slice(2);
const apiKey = process.env.NOBA_API_KEY;
const secretKey = process.env.NOBA_API_SECRET;
const requestMethod = args[0];
const path = args[1];
const timestamp = 0;
const body = args[2] ? args[2] : "{}";

console.log(createHeaderSignature(apiKey, secretKey, requestMethod, path, timestamp, body));

function createHeaderSignature(apiKey, secretKey, requestMethod, path, timestamp, body) {
    const signatureString = cryptoJS.enc.Utf8.parse(`${timestamp}${apiKey}${requestMethod}${path}${body}`);
    return cryptoJS.enc.Hex.stringify(cryptoJS.HmacSHA256(signatureString, secretKey));