Authentication & Request Signing

{t}
{METHOD}
{path}
{idempotency-key}      ← write methods only
{sha256_hex(rawBody)}

{t}\n{METHOD}\n{path}\n[{idempotency-key}\n]{sha256_hex(rawBody || "")}

signature = hex(hmac_sha256(apiSecret, canonicalString))
X-Signature: t={t},v1={signature}

1787735662
GET
/api/v1/invoices/clyv3n8x40001qh7m2k9d5b1t
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

1787735662
POST
/api/v1/invoices
9f2b1c44-7a0e-4d63-9f18-2c5b7ea31d04
{sha256_hex of the JSON body}

import { createHash, createHmac, randomUUID } from 'node:crypto';

const BASE = 'https://api2.havala.io';
const WRITE = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);

export async function havala(method: string, path: string, body?: unknown) {
  // One serialisation, used for both the hash and the wire.
  const raw = body === undefined ? '' : JSON.stringify(body);
  const t = Math.floor(Date.now() / 1000).toString();
  const bodyHash = createHash('sha256').update(raw, 'utf8').digest('hex');

  const headers: Record<string, string> = {
    'X-API-Key': process.env.HAVALA_API_KEY!,
    'Content-Type': 'application/json',
  };

  const parts = [t, method, path];
  if (WRITE.has(method)) {
    const idempotencyKey = randomUUID();
    headers['Idempotency-Key'] = idempotencyKey;
    parts.push(idempotencyKey);
  }
  parts.push(bodyHash);

  const signature = createHmac('sha256', process.env.HAVALA_API_SECRET!)
    .update(parts.join('\n'))
    .digest('hex');
  headers['X-Signature'] = `t=${t},v1=${signature}`;

  const res = await fetch(BASE + path, {
    method,
    headers,
    body: raw === '' ? undefined : raw,
  });
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
  return res.json();
}

import hashlib
import hmac
import json
import os
import time
import uuid

import requests

BASE = "https://api2.havala.io"
WRITE = {"POST", "PUT", "PATCH", "DELETE"}


def havala(method: str, path: str, body=None) -> requests.Response:
    # separators= drops the spaces json.dumps adds by default. Which form you
    # pick does not matter; that these are the bytes you post does.
    raw = b"" if body is None else json.dumps(body, separators=(",", ":")).encode()
    t = str(int(time.time()))
    body_hash = hashlib.sha256(raw).hexdigest()

    headers = {
        "X-API-Key": os.environ["HAVALA_API_KEY"],
        "Content-Type": "application/json",
    }

    parts = [t, method, path]
    if method in WRITE:
        idempotency_key = str(uuid.uuid4())
        headers["Idempotency-Key"] = idempotency_key
        parts.append(idempotency_key)
    parts.append(body_hash)

    signature = hmac.new(
        os.environ["HAVALA_API_SECRET"].encode(),
        "\n".join(parts).encode(),
        hashlib.sha256,
    ).hexdigest()
    headers["X-Signature"] = f"t={t},v1={signature}"

    return requests.request(method, BASE + path, headers=headers, data=raw, timeout=30)

<?php

const HAVALA_BASE = 'https://api2.havala.io';
const HAVALA_WRITE = ['POST', 'PUT', 'PATCH', 'DELETE'];

function havala(string $method, string $path, ?array $body = null): array
{
    // json_encode once. Flags change the bytes, and the bytes are the digest.
    $raw = $body === null ? '' : json_encode($body, JSON_UNESCAPED_SLASHES);
    $t = (string) time();
    $bodyHash = hash('sha256', $raw);

    $headers = [
        'X-API-Key: ' . getenv('HAVALA_API_KEY'),
        'Content-Type: application/json',
    ];

    $parts = [$t, $method, $path];
    if (in_array($method, HAVALA_WRITE, true)) {
        $idempotencyKey = bin2hex(random_bytes(16));
        $headers[] = 'Idempotency-Key: ' . $idempotencyKey;
        $parts[] = $idempotencyKey;
    }
    $parts[] = $bodyHash;

    // hash_hmac returns lowercase hex, which is what the header regex demands.
    $signature = hash_hmac('sha256', implode("\n", $parts), getenv('HAVALA_API_SECRET'));
    $headers[] = 'X-Signature: t=' . $t . ',v1=' . $signature;

    $ch = curl_init(HAVALA_BASE . $path);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_HTTPHEADER     => $headers,
        CURLOPT_POSTFIELDS     => $raw,
        CURLOPT_RETURNTRANSFER => true,
    ]);

    $response = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);

    return ['status' => $status, 'body' => json_decode($response, true)];
}

package havala

import (
	"bytes"
	"crypto/hmac"
	"crypto/rand"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"strconv"
	"strings"
	"time"
)

const baseURL = "https://api2.havala.io"

func isWrite(method string) bool {
	switch method {
	case http.MethodPost, http.MethodPut, http.MethodPatch, http.MethodDelete:
		return true
	}
	return false
}

// Do signs and sends one gateway request. body may be nil for GET and DELETE.
func Do(method, path string, body any) (*http.Response, error) {
	raw := []byte{}
	if body != nil {
		encoded, err := json.Marshal(body)
		if err != nil {
			return nil, err
		}
		raw = encoded
	}

	t := strconv.FormatInt(time.Now().Unix(), 10)
	sum := sha256.Sum256(raw)

	req, err := http.NewRequest(method, baseURL+path, bytes.NewReader(raw))
	if err != nil {
		return nil, err
	}
	req.Header.Set("X-API-Key", os.Getenv("HAVALA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	parts := []string{t, method, path}
	if isWrite(method) {
		buf := make([]byte, 16)
		if _, err := rand.Read(buf); err != nil {
			return nil, err
		}
		idempotencyKey := hex.EncodeToString(buf)
		req.Header.Set("Idempotency-Key", idempotencyKey)
		parts = append(parts, idempotencyKey)
	}
	parts = append(parts, hex.EncodeToString(sum[:]))

	mac := hmac.New(sha256.New, []byte(os.Getenv("HAVALA_API_SECRET")))
	mac.Write([]byte(strings.Join(parts, "\n")))
	req.Header.Set("X-Signature", fmt.Sprintf("t=%s,v1=%s", t, hex.EncodeToString(mac.Sum(nil))))

	return http.DefaultClient.Do(req)
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.time.Instant;
import java.util.HexFormat;
import java.util.Set;
import java.util.UUID;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public final class HavalaClient {

    private static final String BASE = "https://api2.havala.io";
    private static final Set<String> WRITE = Set.of("POST", "PUT", "PATCH", "DELETE");
    private static final HttpClient HTTP = HttpClient.newHttpClient();

    private final String apiKey;
    private final String apiSecret;

    public HavalaClient(String apiKey, String apiSecret) {
        this.apiKey = apiKey;
        this.apiSecret = apiSecret;
    }

    /** json is the already-serialised body, or "" for GET and DELETE. */
    public HttpResponse<String> send(String method, String path, String json) throws Exception {
        byte[] raw = json.getBytes(StandardCharsets.UTF_8);
        String t = Long.toString(Instant.now().getEpochSecond());

        // HexFormat emits lowercase, which the X-Signature regex requires.
        HexFormat hex = HexFormat.of();
        String bodyHash = hex.formatHex(MessageDigest.getInstance("SHA-256").digest(raw));

        HttpRequest.Builder req = HttpRequest.newBuilder(URI.create(BASE + path))
                .method(method, HttpRequest.BodyPublishers.ofByteArray(raw))
                .header("X-API-Key", apiKey)
                .header("Content-Type", "application/json");

        StringBuilder canonical = new StringBuilder()
                .append(t).append('\n')
                .append(method).append('\n')
                .append(path).append('\n');

        if (WRITE.contains(method)) {
            String idempotencyKey = UUID.randomUUID().toString();
            req.header("Idempotency-Key", idempotencyKey);
            canonical.append(idempotencyKey).append('\n');
        }
        canonical.append(bodyHash);

        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(apiSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        String signature = hex.formatHex(
                mac.doFinal(canonical.toString().getBytes(StandardCharsets.UTF_8)));

        req.header("X-Signature", "t=" + t + ",v1=" + signature);
        return HTTP.send(req.build(), HttpResponse.BodyHandlers.ofString());
    }
}

using System.Net.Http.Headers;
using System.Security.Cryptography;
using System.Text;

public sealed class HavalaClient(string apiKey, string apiSecret)
{
    private static readonly HttpClient Http =
        new() { BaseAddress = new Uri("https://api2.havala.io") };

    private static readonly HashSet<string> Write = ["POST", "PUT", "PATCH", "DELETE"];

    /// <param name="json">The already-serialised body, or "" for GET and DELETE.</param>
    public async Task<HttpResponseMessage> SendAsync(
        HttpMethod method, string path, string json = "")
    {
        var raw = Encoding.UTF8.GetBytes(json);
        var t = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();

        // Convert.ToHexString returns uppercase; the header regex accepts only
        // lowercase, so both digests are lowered here.
        var bodyHash = Convert.ToHexString(SHA256.HashData(raw)).ToLowerInvariant();

        var request = new HttpRequestMessage(method, path);
        request.Headers.Add("X-API-Key", apiKey);

        var parts = new List<string> { t, method.Method, path };
        if (Write.Contains(method.Method))
        {
            var idempotencyKey = Guid.NewGuid().ToString();
            request.Headers.Add("Idempotency-Key", idempotencyKey);
            parts.Add(idempotencyKey);
        }
        parts.Add(bodyHash);

        var signature = Convert.ToHexString(
            HMACSHA256.HashData(
                Encoding.UTF8.GetBytes(apiSecret),
                Encoding.UTF8.GetBytes(string.Join("\n", parts)))
        ).ToLowerInvariant();
        request.Headers.Add("X-Signature", $"t={t},v1={signature}");

        if (raw.Length > 0)
        {
            request.Content = new ByteArrayContent(raw);
            request.Content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
        }

        return await Http.SendAsync(request);
    }
}