Authentication

Every request must carry HMAC-SHA256 authentication headers. The signed payload is canonicalised so a captured signature cannot be replayed against a different endpoint, body or window.

The agent rejects requests:

• with a timestamp older than 300 seconds,
• whose nonce was already seen inside the replay window (twice the 300 s timestamp tolerance plus 60 s),
• whose signature, recomputed server-side, doesn't match,
• whose path drifts from the signed one after posixpath.normpath and matrix-param stripping (so trailing ;foo=bar cannot bypass the path binding).

Account-bound (reseller) keys

A key minted from the client panel by a reseller account (Settings → API Access) signs requests exactly like a server key, but is served as that reseller: it reaches only /api/v1/client/* and acts there with the reseller's ownership checks and ACL plan. What such a key gets back:

The key's scope is fixed (client) and cannot be widened; a reseller holds at most 10 keys. Management endpoints for the reseller's own keys: GET/POST /api/v1/client/api-keys, PUT /api/v1/client/api-keys/{key_id}, POST /api/v1/client/api-keys/{key_id}/revoke, DELETE /api/v1/client/api-keys/{key_id}, GET /api/v1/client/api-keys/logs — session cookie only. The administrator sees every key under GET /api/v1/system/api-keys; the owner field names the reseller (null for server-wide keys).

Canonical signing payload (v2)

METHOD\nPATH\nTIMESTAMP\nNONCE\nBODY

PATH is the agent-visible path (the part after the host, including the /api/v1/... prefix). BODY is the raw HTTP body bytes decoded as UTF-8 with surrogateescape (binary uploads are signable without re-encoding).

Reference Python signer

import hashlib, hmac, json, secrets, time
from urllib.request import Request, urlopen
import ssl

API_KEY    = "your-api-key"
API_SECRET = "your-api-secret"
BASE_URL   = "https://panel.example.com"

def sign(method: str, path: str, body: bytes = b"") -> dict[str, str]:
    ts    = str(int(time.time()))
    nonce = secrets.token_hex(16)
    body_str = body.decode("utf-8", errors="surrogateescape")
    payload  = f"{method}\n{path}\n{ts}\n{nonce}\n{body_str}"
    sig = hmac.new(
        API_SECRET.encode("utf-8"),
        payload.encode("utf-8", errors="surrogateescape"),
        hashlib.sha256,
    ).hexdigest()
    return {
        "X-WHost-Key":       API_KEY,
        "X-WHost-Timestamp": ts,
        "X-WHost-Nonce":     nonce,
        "X-WHost-Signature": sig,
        "Content-Type":      "application/json",
    }

body = json.dumps({"username": "alice"}).encode("utf-8")
headers = sign("POST", "/api/v1/accounts", body)
req = Request(f"{BASE_URL}/api/v1/accounts", data=body,
              headers=headers, method="POST")
ctx = ssl.create_default_context()
ctx.check_hostname = False
ctx.verify_mode = ssl.CERT_NONE  # remove in production
print(urlopen(req, context=ctx).read())

Signers in other languages live next to this file:

• PHP — docs/developer/examples/hmac-example.php
• JavaScript / Node.js — docs/developer/examples/hmac-example.js
• Go — docs/developer/examples/hmac-example.go
• Ruby — docs/developer/examples/hmac-example.rb
• Bash / POSIX sh — docs/developer/examples/hmac-example.sh

Admin session cookie (browser-only)

The /admin/* panel and the /client/* panel mint an httpOnly session cookie via POST /api/v1/auth/login (then /api/v1/auth/login/2fa when 2FA is enabled). SDKs and partner integrations should always use HMAC instead — sessions are scoped to a browser context and rotate on every privilege change.