🔐Authentication

Ensuring Secure and Authenticated API Requests Using HMAC SHA256.

1. Signing an API Request

To ensure the security and integrity of your API requests, you need to sign your requests using HMAC SHA256.

This process involves creating a specific string from your request, and then generating a signature using your secret key.

Requirement: Request an API Key and Secret Key from NovaX Support at [email protected] to access APIs.

2. Step-by-Step Guide

This guide provides a clear process for signing an API request, from converting a JSON body to a query string (handling nested fields with a dot .), constructing the string to sign, and finally signing it using HMAC SHA256.

This ensures your API requests are secure and authenticated.

2.1 Create the Query String from JSON

Depending on your programming language, use the following methods to convert a JSON object to a query string. Note that nested fields are handled using a dot (.).

const qs = require('qs');

const jsonObj = {
    field1: "value2",
    nestedField: {
        nestedField1: "nestedValue1"
    }
};

const queryString = qs.stringify(jsonObj, { encode: false, delimiter: '&', allowDots: true });
console.log(queryString); // Output: field1=value2&nestedField.nestedField1=nestedValue1

using System;
using System.Collections.Generic;
using System.Web;
using System.Text.Json;

public class Program
{
    public static void Main()
    {
        var jsonObj = new Dictionary<string, object>
        {
            { "field1", "value2" },
            { "nestedField", new Dictionary<string, object> { { "nestedField1", "nestedValue1" } } }
        };

        var flatDict = FlattenObject(jsonObj);
        var query = HttpUtility.ParseQueryString(string.Empty);

        foreach (var kvp in flatDict)
        {
            query[kvp.Key] = kvp.Value.ToString();
        }

        string queryString = query.ToString().Replace("&amp;", "&");
        Console.WriteLine(queryString); // Output: field1=value2&nestedField.nestedField1=nestedValue1
    }

    public static Dictionary<string, object> FlattenObject(Dictionary<string, object> obj, string parentKey = "", string sep = ".")
    {
        var items = new Dictionary<string, object>();
        foreach (var kvp in obj)
        {
            var newKey = string.IsNullOrEmpty(parentKey) ? kvp.Key : $"{parentKey}{sep}{kvp.Key}";

            if (kvp.Value is Dictionary<string, object> nestedDict)
            {
                var nestedItems = FlattenObject(nestedDict, newKey, sep);
                foreach (var nestedKvp in nestedItems)
                {
                    items[nestedKvp.Key] = nestedKvp.Value;
                }
            }
            else
            {
                items[newKey] = kvp.Value;
            }
        }
        return items;
    }
}

$jsonObj = [
    "field1" => "value2",
    "nestedField" => [
        "nestedField1" => "nestedValue1"
    ]
];

function flattenArray($arr, $parentKey = '', $sep = '.') {
    $items = [];
    foreach ($arr as $key => $value) {
        $newKey = $parentKey ? $parentKey . $sep . $key : $key;
        if (is_array($value)) {
            $items = array_merge($items, flattenArray($value, $newKey, $sep));
        } else {
            $items[$newKey] = $value;
        }
    }
    return $items;
}

$flatArr = flattenArray($jsonObj);
$queryString = urldecode(http_build_query($flatArr));
echo $queryString; // Output: field1=value2&nestedField.nestedField1=nestedValue1

2.2 Construct the String to Sign

FULL URL:

https://api.com/users?test=xxx

API PATH:

/users?test=xxx

QUERYSTRING FROM BODY:

field1=value2&nestedField.nestedField1=nestedValue1

Construct the string to sign by concatenating the API PATH and the QUERYSTRING FROM BODY:

stringToSign = "/users?test=xxxfield1=value2&nestedField.nestedField1=nestedValue1"

2.3 Sign the String using HMAC SHA256

Use your programming language's libraries to sign the string using HMAC SHA256.

const crypto = require('crypto');
const secretKey = 'your-secret-key';
const stringToSign = '/users?test=xxxfield1=value2&nestedField.nestedField1=nestedValue1';

const signature = crypto.createHmac('sha256', secretKey)
                        .update(stringToSign)
                        .digest('hex');
console.log(signature);

using System;
using System.Text;
using System.Security.Cryptography;

public class Program
{
    public static void Main()
    {
        string secretKey = "your-secret-key";
        string stringToSign = "/users?test=xxxfield1=value2&nestedField.nestedField1=nestedValue1";

        string signature = SignString(secretKey, stringToSign);
        Console.WriteLine(signature);
    }

    public static string SignString(string key, string data)
    {
        var encoding = new System.Text.ASCIIEncoding();
        byte[] keyByte = encoding.GetBytes(key);
        byte[] messageBytes = encoding.GetBytes(data);

        using (var hmacsha256 = new HMACSHA256(keyByte))
        {
            byte[] hashmessage = hmacsha256.ComputeHash(messageBytes);
            return BitConverter.ToString(hashmessage).Replace("-", "").ToLower();
        }
    }
}

$secretKey = 'your-secret-key';
$stringToSign = '/users?test=xxxfield1=value2&nestedField.nestedField1=nestedValue1';

$signature = hash_hmac('sha256', $stringToSign, $secretKey);
echo $signature;

PreviousAPI Integration Setup NextRequests

Last updated 1 year ago

hashtag1. Signing an API Request

hashtag2. Step-by-Step Guide

hashtag2.1 Create the Query String from JSON

hashtag2.2 Construct the String to Sign

hashtag2.3 Sign the String using HMAC SHA256

1. Signing an API Request

2. Step-by-Step Guide

2.1 Create the Query String from JSON

2.2 Construct the String to Sign

2.3 Sign the String using HMAC SHA256