Authenticate API Requests

To ensure the security and integrity of every request, The Dispersed API uses an HMAC (Hash-based Message Authentication Code) signature. This proves you possess the secret key without ever transmitting it over the network.

Required Headers

Every API request must include these four headers:

Header	Description	Example
`X-API-Key`	Your API Key public key	`pk_abc123...`
`X-Time`	Unix timestamp in milliseconds	`1706918400000`
`X-Nonce`	Random 16-byte hex string (32 characters)	`a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6`
`X-Signature`	HMAC-SHA256 signature of the canonical string	`e3b0c442...`

Authentication: HMAC Signature Scheme

Dispersed API requests require HMAC-SHA256 authentication, constructed by signing a 7-part, pipe-delimited canonical string (publicKey|timestamp|nonce|METHOD|pathname|queryString|bodySha256). Key requirements include sorting query parameters alphabetically (without the leading ”?”), hashing the body with SHA-256 (using an empty string hash for empty bodies), and creating a 64-character lowercase hex signature from the final string. The signature proves you possess the secret key without transmitting it.

Steps to build the HMAC Signature

1. Build the Canonical String

The “Canonical String” is a standardized version of your request. You must concatenate exactly seven components using the pipe (|) character as a delimiter.

publicKey|timestamp|nonce|METHOD|pathname|queryString|bodySha256

Example:

pk_abc123|1706918400000|a1b2c3d4e5f6a7b8|GET|/v1/jobs|limit=10&page=1|e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Component	Description
`publicKey`	Your API key’s public key (`pk_...`) is your unique API identifier
`timestamp`	Unix timestamp in milliseconds (same as `X-Time` header)
`nonce`	Random 16-byte hex string, 32 characters (same as `X-Nonce` header)
`METHOD`	HTTP method in all uppercase (`GET`, `POST`, `PATCH`, `DELETE`)
`pathname`	The URI path starting with `/` (e.g., `/v1/jobs`)
`queryString`	The Canonical Query String (see rules below)
`bodySha256`	SHA-256 hash of the canonicalized request body (hex-encoded, lowercase)

Rules For The Query String (No Leading `?`)

The queryString component should contain only the data parameters.

✅ DO: limit=10&sort=desc
❌ DON’T: ?limit=10&sort=desc (The ? is a separator for the URI, not part of the data).

Handling Empty Fields (`||`)

If a component is empty (common with queryString or bodySha256), you must still include the pipe delimiter. This maintains the “column” structure of the string.

Example of an empty query string: ...|METHOD|pathname||bodySha256
The || indicates that the 6th component is an empty string.

Sort Query Parameters

To ensure deterministic signatures:

Sort parameter keys alphabetically (lexicographic order)
For duplicate keys, sort their values alphabetically
URL-encode keys and values
Join with & (no leading ?)

Example: ?z=3&a=1&b=2 becomes a=1&b=2&z=3 Multi-value example: ?tag=zebra&tag=apple becomes tag=apple&tag=zebra

Complete Examples

Example A: A Filtered GET Request

Target URI: https://example.com

Component	Value
publicKey	`pk_abc123`
timestamp	`1706918400000`
nonce	`a1b2c3d4e5f6a7b8`
METHOD	`GET`
pathname	`/v1/jobs`
queryString	`limit=10&page=1`
bodySha256	`e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855...` (Hash of an empty string)

Resulting Canonical String:

pk_abc123|1706918400000|a1b2c3d4e5f6a7b8|GET|/v1/jobs|limit=10&page=1|e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Example B: A Simple GET Request (No Parameters)

Target URI: https://example.com

Component	Value
publicKey	`pk_abc123`
timestamp	`1706918400000`
nonce	`a1b2c3d4e5f6a7b8`
METHOD	`GET`
pathname	`/v1/jobs`
queryString
bodySha256	`e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855...` (Hash of an empty string)

Resulting Canonical String:

pk_abc123|1706918400000|a1b2c3d4e5f6a7b8|GET|/v1/jobs||e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

(Note the || where the query string would normally be.)

2. Canonicalize the Request Body

Turn a “messy” JSON object into a single, predictable string so that a hash can be calculated. For JSON bodies (Content-Type: application/json):

Parse the JSON. Before you can secure the data, you must turn it into a “clean” data structure so that your code can manipulate it.
Re-serialize with:
- Keys sorted alphabetically (recursive for nested objects): Original: {"status": "active", "id": 101} Sorted: {"id": 101, "status": "active"} Recursive: If there is an object inside the object, you must sort those keys too.
- Compact format (no whitespace): {"key":"value"} not { "key": "value" } Human-readable JSON has spaces and newlines. Computers don’t need them. You must strip all “extra” characters. (Note: No spaces after colons or commas.)
- ASCII-safe encoding If you have special characters (like emojis or non-English letters), you must ensure they are encoded consistently (usually using \u escapes for non-ASCII or just standard UTF-8 bytes) so the hash does not change based on the computer’s language settings.
Compute SHA-256 hash of the UTF-8 encoded result

Example: { "z": 1, "a": 2 } becomes {"a":2,"z":1} For empty bodies (GET, DELETE, or POST with no body), hash an empty byte array:

sha256("") = e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

3. Sign with HMAC-SHA256

Once you have built the compact, sorted Canonical String, use your Secret Key to sign it using the HMAC-SHA256 algorithm. Your secret key (sk_...) is used to compute the HMAC-SHA256 signature of the canonical string. Output as lowercase hex (64 characters) and pass the resulting hex string in your request headers as X-Signature.

Code Examples

TypeScript
Python
Go

import * as crypto from 'crypto';

// Configuration
const PUBLIC_KEY = process.env.DISNET_PUBLIC_KEY || 'pk_your_public_key';
const SECRET_KEY = process.env.DISNET_SECRET_KEY || 'sk_your_secret_key';
const BASE_URL = process.env.DISNET_API_BASE_URL || 'https://api.dispersed.com';

function canonicalizeJson(value: unknown): unknown {
  if (value === null || typeof value !== 'object') {
    return value;
  }
  if (Array.isArray(value)) {
    return value.map(canonicalizeJson);
  }
  const sorted: Record<string, unknown> = {};
  for (const key of Object.keys(value as object).sort()) {
    sorted[key] = canonicalizeJson((value as Record<string, unknown>)[key]);
  }
  return sorted;
}

function canonicalizeQueryString(params: URLSearchParams): string {
  const uniqueKeys = [...new Set(Array.from(params.keys()))].sort();
  return uniqueKeys
    .flatMap((key) => {
      const values = params.getAll(key).sort();
      return values.map(
        (value) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`
      );
    })
    .join('&');
}

function generateAuthHeaders(
  method: string,
  pathname: string,
  query: URLSearchParams | Record<string, string> = new URLSearchParams(),
  body: unknown = null
): Record<string, string> {
  const timestamp = Date.now().toString();
  const nonce = crypto.randomBytes(16).toString('hex');

  const params =
    query instanceof URLSearchParams ? query : new URLSearchParams(query);
  const queryString = canonicalizeQueryString(params);

  let bodySha256: string;
  if (body !== null && body !== undefined) {
    const canonicalBody = JSON.stringify(canonicalizeJson(body));
    bodySha256 = crypto
      .createHash('sha256')
      .update(canonicalBody)
      .digest('hex');
  } else {
    bodySha256 = crypto.createHash('sha256').update('').digest('hex');
  }

  const canonicalString = [
    PUBLIC_KEY,
    timestamp,
    nonce,
    method.toUpperCase(),
    pathname,
    queryString,
    bodySha256,
  ].join('|');

  const signature = crypto
    .createHmac('sha256', SECRET_KEY)
    .update(canonicalString)
    .digest('hex');

  return {
    'X-API-Key': PUBLIC_KEY,
    'X-Time': timestamp,
    'X-Nonce': nonce,
    'X-Signature': signature,
    'Content-Type': 'application/json',
    Accept: 'application/json',
  };
}

// Example: List jobs
async function listJobs(page = 1, limit = 20): Promise<unknown> {
  const query = new URLSearchParams({
    page: String(page),
    limit: String(limit),
  });
  const pathname = '/v1/jobs';
  const headers = generateAuthHeaders('GET', pathname, query);

  const response = await fetch(`${BASE_URL}${pathname}?${query}`, {
    method: 'GET',
    headers,
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`API Error: ${error.error?.message || response.statusText}`);
  }

  return response.json();
}

import hashlib
import hmac
import json
import os
import secrets
import time
from typing import Any, Optional
from urllib.parse import urlencode, parse_qs
import requests

PUBLIC_KEY = os.environ.get("DISPERSED_PUBLIC_KEY", "pk_your_public_key")
SECRET_KEY = os.environ.get("DISPERSED_SECRET_KEY", "sk_your_secret_key")
BASE_URL = os.environ.get("DISPERSED_API_BASE_URL", "https://api.dispersed.com")


def canonicalize_json(value: Any) -> Any:
    if isinstance(value, dict):
        return {k: canonicalize_json(v) for k, v in sorted(value.items())}
    if isinstance(value, list):
        return [canonicalize_json(item) for item in value]
    return value


def generate_auth_headers(
    method: str,
    pathname: str,
    query: Optional[dict[str, str]] = None,
    body: Optional[dict[str, Any]] = None,
) -> dict[str, str]:
    timestamp = str(int(time.time() * 1000))
    nonce = secrets.token_hex(16)

    query_string = urlencode(sorted((query or {}).items()))

    if body is not None:
        canonical_body = json.dumps(
            canonicalize_json(body),
            separators=(",", ":"),
            ensure_ascii=True,
            allow_nan=False,
        )
        body_sha256 = hashlib.sha256(canonical_body.encode("utf-8")).hexdigest()
    else:
        body_sha256 = hashlib.sha256(b"").hexdigest()

    canonical_string = "|".join([
        PUBLIC_KEY,
        timestamp,
        nonce,
        method.upper(),
        pathname,
        query_string,
        body_sha256,
    ])

    signature = hmac.new(
        key=SECRET_KEY.encode("utf-8"),
        msg=canonical_string.encode("utf-8"),
        digestmod=hashlib.sha256,
    ).hexdigest()

    return {
        "X-API-Key": PUBLIC_KEY,
        "X-Time": timestamp,
        "X-Nonce": nonce,
        "X-Signature": signature,
        "Content-Type": "application/json",
        "Accept": "application/json",
    }


# Example: List jobs
def list_jobs(page: int = 1, limit: int = 20) -> dict[str, Any]:
    pathname = "/v1/jobs"
    query = {"page": str(page), "limit": str(limit)}
    headers = generate_auth_headers("GET", pathname, query=query)

    response = requests.get(
        f"{BASE_URL}{pathname}",
        params=query,
        headers=headers,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

package main

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

var (
	PublicKey = getEnv("DISPERSED_PUBLIC_KEY", "pk_your_public_key")
	SecretKey = getEnv("DISPERSED_SECRET_KEY", "sk_your_secret_key")
	BaseURL   = getEnv("DISPERSED_API_BASE_URL", "https://api.dispersed.com")
)

func getEnv(key, fallback string) string {
	if value := os.Getenv(key); value != "" {
		return value
	}
	return fallback
}

func canonicalizeQueryString(query url.Values) string {
	if len(query) == 0 {
		return ""
	}
	keys := make([]string, 0, len(query))
	for k := range query {
		keys = append(keys, k)
	}
	sort.Strings(keys)

	var parts []string
	for _, k := range keys {
		values := query[k]
		sortedValues := make([]string, len(values))
		copy(sortedValues, values)
		sort.Strings(sortedValues)
		for _, v := range sortedValues {
			parts = append(parts, url.QueryEscape(k)+"="+url.QueryEscape(v))
		}
	}
	return strings.Join(parts, "&")
}

func generateAuthHeaders(method, pathname string, query url.Values, body interface{}) (http.Header, error) {
	timestamp := strconv.FormatInt(time.Now().UnixMilli(), 10)

	b := make([]byte, 16)
	if _, err := rand.Read(b); err != nil {
		return nil, err
	}
	nonce := hex.EncodeToString(b)

	queryString := canonicalizeQueryString(query)

	var bodySha256 string
	if body != nil {
		jsonBytes, err := json.Marshal(body)
		if err != nil {
			return nil, err
		}
		hash := sha256.Sum256(jsonBytes)
		bodySha256 = hex.EncodeToString(hash[:])
	} else {
		hash := sha256.Sum256([]byte{})
		bodySha256 = hex.EncodeToString(hash[:])
	}

	canonicalString := strings.Join([]string{
		PublicKey, timestamp, nonce, strings.ToUpper(method),
		pathname, queryString, bodySha256,
	}, "|")

	mac := hmac.New(sha256.New, []byte(SecretKey))
	mac.Write([]byte(canonicalString))
	signature := hex.EncodeToString(mac.Sum(nil))

	headers := http.Header{}
	headers.Set("X-API-Key", PublicKey)
	headers.Set("X-Time", timestamp)
	headers.Set("X-Nonce", nonce)
	headers.Set("X-Signature", signature)
	headers.Set("Content-Type", "application/json")
	return headers, nil
}

// Example: List jobs
func ListJobs(page, limit int) ([]byte, error) {
	pathname := "/v1/jobs"
	query := url.Values{
		"page":  {strconv.Itoa(page)},
		"limit": {strconv.Itoa(limit)},
	}

	headers, err := generateAuthHeaders("GET", pathname, query, nil)
	if err != nil {
		return nil, err
	}

	req, _ := http.NewRequest("GET", BaseURL+pathname+"?"+query.Encode(), nil)
	req.Header = headers

	resp, err := (&http.Client{Timeout: 30 * time.Second}).Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()

	return io.ReadAll(resp.Body)
}

Common Errors

Status	Error	Cause	Solution
400	Missing required header	`X-API-Key`, `X-Time`, `X-Nonce`, or `X-Signature` not provided	Include all four headers
400	Invalid X-Time header	`X-Time` is not a valid integer timestamp	Use milliseconds since Unix epoch
400	Invalid X-Nonce header	Nonce is not a 32-character hex string	Generate 16 random bytes as hex
400	Invalid or reused nonce	Nonce was already used within 24 hours	Generate a fresh nonce per request
401	Invalid signature	Signature doesn’t match expected value	Verify canonical string construction
401	Invalid API key	Public key doesn’t exist or is revoked/deleted	Check your public key is correct
401	API key has expired	Key past expiration date	Create a new API key
403	Timestamp out of range	`X-Time` differs from server time by more than 5 minutes	Sync your clock, use current time
403	Insufficient permissions	Key lacks required permission for this endpoint	Create key with needed permissions
403	IP address not allowed	Request from non-allowlisted IP	Update key’s allowed IPs

Troubleshooting Signatures

If you’re getting “Invalid signature” errors, verify each component of the canonical string:

Checklist

Timestamp precision
- Must be milliseconds, not seconds
- Example: 1706918400000 (13 digits), not 1706918400 (10 digits)
Nonce format
- Exactly 32 lowercase hex characters (representing 16 random bytes)
- Use cryptographic random: crypto.randomBytes(), secrets.token_hex(), or crypto/rand
- Example: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
Body canonicalization
- JSON keys sorted recursively (nested objects too)
- Compact format with no whitespace: {"a":1,"b":2} not { "a": 1, "b": 2 }
- Use separators=(",", ":") in Python, compact marshaling in Go/TypeScript
Query string canonicalization
- Sort both keys and values alphabetically
- No leading ? character
- Use RFC 3986 percent-encoding (spaces as %20, not +)
- Example: ?z=3&a=1 → a=1&z=3
Empty body handling
- Hash an empty byte array, not null or undefined
- SHA-256 of empty: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Pathname normalization
- No trailing slashes (except root /)
- Collapse multiple slashes: //api//v1 → /api/v1
- No query string (that’s a separate component)
Encoding
- UTF-8 for all strings
- Lowercase hex for SHA-256 hash and signature

Debug Your Canonical String

Print your canonical string before signing to verify each component:

publicKey|timestamp|nonce|METHOD|pathname|queryString|bodySha256

Ensure there are exactly 7 components separated by 6 pipe characters.

Keep it Secret, Keep it Safe

Preferred: Store secret keys in a dedicated secrets manager (AWS Secrets Manager, HashiCorp Vault, Google Secret Manager, Azure Key Vault)
Alternative: Use environment variables if a secrets manager is not available (NOTE: environment variables can be exposed through process listings, logs, or crash dumps)
Never hardcode keys in source code or commit them to version control
Use cryptographically secure random number generators for nonces
Implement request timeouts to prevent hanging connections
Rotate API keys periodically and revoke unused keys promptly

Documentation Index

​Required Headers

​Authentication: HMAC Signature Scheme

​Steps to build the HMAC Signature

​1. Build the Canonical String

​Rules For The Query String (No Leading ?)

​Handling Empty Fields (||)

​Sort Query Parameters

​Complete Examples

​2. Canonicalize the Request Body

​3. Sign with HMAC-SHA256

​Code Examples

​Common Errors

​Troubleshooting Signatures

​Checklist

​Debug Your Canonical String