🔐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 Tyga Support at [e-mail] 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 (.).

JavaScript

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

C#

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;
    }
}

PHP

$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.

JavaScript

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);

C#

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();
        }
    }
}

PHP

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

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