Authenticate API Requests

All requests to the Dispersed API require authentication using an API Key with HMAC signature verification.

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

---

HMAC Signature Scheme

The signature proves you possess the secret key without transmitting it. Here’s how it works:

1. Build the Canonical String

Concatenate these seven components with | (pipe) as the 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_...)
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 uppercase (GET, POST, PATCH, DELETE)
pathname	URL path without query string, normalized (e.g., /v1/jobs)
queryString	Canonicalized query string (sorted alphabetically, no ? prefix)
bodySha256	SHA-256 hash of the canonicalized request body (hex-encoded, lowercase)

2. Canonicalize the Query String

Sort query parameters to ensure deterministic signatures:

1. Sort parameter keys alphabetically (lexicographic order)
2. For duplicate keys, sort their values alphabetically
3. URL-encode keys and values
4. 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

3. Canonicalize the Request Body

For JSON bodies (Content-Type: application/json):

1. Parse the JSON
2. Re-serialize with:
   • Keys sorted alphabetically (recursive for nested objects)
   • Compact format (no whitespace): {"key":"value"} not { "key": "value" }
   • ASCII-safe encoding
3. 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

4. Sign with HMAC-SHA256

Use your secret key (sk_...) to compute an HMAC-SHA256 signature of the canonical string. Output as lowercase hex (64 characters).

---

Code Examples

TypeScript

import * as crypto from 'crypto';

// Configuration
const PUBLIC_KEY = process.env.DISPERSED_PUBLIC_KEY || 'pk_your_public_key';
const SECRET_KEY = process.env.DISPERSED_SECRET_KEY || 'sk_your_secret_key';
const BASE_URL = process.env.DISPERSED_API_BASE_URL || 'https://api.compute.x.io';

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

Python

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.compute.x.io")


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

Go

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.compute.x.io")
)

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

1. Timestamp precision
   • Must be milliseconds, not seconds
   • Example: 1706918400000 (13 digits), not 1706918400 (10 digits)
2. Nonce format
   • Exactly 32 lowercase hex characters (representing 16 random bytes)
   • Use cryptographic random: crypto.randomBytes(), secrets.token_hex(), or crypto/rand
   • Example: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
3. 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
4. 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
5. Empty body handling
   • Hash an empty byte array, not null or undefined
   • SHA-256 of empty: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
6. Pathname normalization
   • No trailing slashes (except root /)
   • Collapse multiple slashes: //api//v1 → /api/v1
   • No query string (that’s a separate component)
7. 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