Authentication

Updated Nov 19, 2026 Markdown

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.

X-WHost-KeyAPI key id (configurable in /admin/api-keys).
X-WHost-TimestampCurrent Unix timestamp (seconds).
X-WHost-Nonce16–256 characters, unique per request (32 hex chars recommended); a replayed nonce is refused.
X-WHost-SignatureHMAC-SHA256(api_secret, "METHOD\nPATH\nTIMESTAMP\nNONCE\nBODY") hex digest.

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:

Request Answer
Any path outside /api/v1/client/ 403 SCOPE_DENIED
/api/v1/client/api-keys*, /api/v1/client/profile* (credential and profile management) 403 HMAC_FORBIDDEN_FOR_CREDENTIAL_MUTATION — browser session only
A sub-account the reseller does not own 404 ACCOUNT_NOT_FOUND
Reseller's ACL plan without api_access, or the account no longer a reseller 403 PERMISSION_DENIED
Owner account suspended, terminated or deleted; key revoked 401 AUTH_FAILED

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)

text
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

Python
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:

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.

Password changes (billing keys)

PATCH /api/v1/accounts/{username}/password (body {"password": "…"}) changes the account's panel password, its system user's password and its default FTP user's password. Over an API key it needs a server-wide key with full access — any Full Access key on the API Access page, the installer's Default API Key included (keys created with "scopes": ["*", "billing"] work the same). A key without full access answers 403 SCOPE_DENIED. The password rules are the same as in the panel (at least 8 characters, at most 72 bytes; 422 VALIDATION_ERROR). The Audit log records the change with the key as actor. A change made here (by a billing key or by the admin session) ends the account's open client panel sessions — the customer's own, a remembered one and an administrator's "log in as client" session; the customer signs in again with the new password.

A billing system signs its customer into the WHost client panel without the password with POST /api/v1/accounts/{username}/login-token (API keys only; an administrator in the panel uses impersonation instead). Body, every field optional: ip — the customer's address, the link then works only from it; ttl — seconds, 10–300, default 60; lang — the panel language to land in. The answer's login_url is relative to the panel address: send the customer's browser to https://<panel address><login_url>.

  • The link is /api/v1/auth/client/login-link#token=<token>. The token rides after #, which a browser never sends: it stays out of the web server's and the CDN's access logs and out of the next page's Referer. The page the link opens reads the token, removes it from the address bar and posts it to POST /api/v1/auth/client/login-token (form field token). Open the URL as it is: a redirect (Location:) keeps the fragment, a URL rebuilt without it lands on the sign-in page.

  • The earlier form, GET /api/v1/auth/client/login-token?token=<token>, still signs in during the 1.x line and is deprecated: WHost no longer issues it, and the agent's own access log writes its token as ***.

  • The first visit consumes the link, whatever the outcome; an unknown, used or expired link, another address than the bound one, or an account that is no longer active lands on the client sign-in page without a session.

  • The session is the customer's own (no impersonation banner) and, like a password sign-in, ends the account's other client sessions. The link skips the account's second factor: the billing system has authenticated the customer.

  • A suspended account answers 403 ACCOUNT_SUSPENDED; an administrator session 403 PERMISSION_DENIED; an account-bound or restricted key 403 SCOPE_DENIED.

  • Links live in the agent's memory: an agent restart drops the unused ones. With an X-Idempotency-Key, a replay returns login_url as "***" — create a new link instead.

Customer phpMyAdmin sign-in (billing systems)

GET /api/v1/accounts/{username}/databases/phpmyadmin-url (API key with full access, or an administrator session) opens phpMyAdmin for the account's customer: a single-use token for a MariaDB user that exists for five minutes with grants on that account's own databases only — the same session the client panel's phpMyAdmin button opens, never the server's root. ?db=<short name> (or the full <username>_<name>) opens that database. The answer is {"login_url": "/phpmyadmin/whost_sso.php?token=…[&db=…]"}, relative to the panel address; send the customer's browser there.

  • An account without databases, or a db the account does not hold, answers 404 DATABASE_NOT_FOUND before any MariaDB user is created; another account's database name is read as a name inside this account.
  • A used token answers 401 on the signon page. The MariaDB user is dropped five minutes after the token was created, used or not, which also ends the phpMyAdmin session: create a new URL for each visit.
  • A restricted or account-bound key answers 403 SCOPE_DENIED; a server without phpMyAdmin answers 200 with error_code: PMA_NOT_INSTALLED.
  • The per-database route GET /accounts/{username}/databases/{db_name}/phpmyadmin-url keeps signing in as root; do not hand its URL to a customer.

Account IP blocks

/api/v1/accounts/{username}/firewall/ip-blocks (API key with full access, or an administrator session) is the account's own block list: an address on it gets 403 on every website of that account and nowhere else — the list is written into the account's vhosts, never into the server firewall. The client panel's Firewall page manages the same list over /api/v1/client/firewall/ip-blocks (the customer's session, or an account-bound key for its own account).

  • GET → [{"id","ip","comment","created_at"}].
  • POST {"ip": "<address or network>", "comment": "<optional, ≤ 255>"} — one IPv4 / IPv6 address, or a network no wider than /16 (IPv4) or /48 (IPv6); 203.0.113.9/24 is stored as 203.0.113.0/24. An address already on the list answers 200 unchanged. Unspecified, multicast, link-local and /0 values, a wider network, control characters in the note and unknown fields answer 422 VALIDATION_ERROR; at most 500 entries per account.
  • DELETE …/ip-blocks/{ip} — the value as listed, URL-encoded (203.0.113.0%2F24); an address that is not on the list answers 404 NOT_FOUND.
  • A write re-renders every vhost of the account and tests the configuration; a configuration the web server refuses keeps the previous list (500 VHOST_CONFIG_ERROR). OpenLiteSpeed / LiteSpeed hosts answer 409 FEATURE_DISABLED.
  • The address is the visitor's as the web server sees it (behind Cloudflare, the real visitor address). The ACME challenge path stays reachable, and a redirect rule (return) is answered before the block applies.
  • The Audit log records firewall_ip_blocked / firewall_ip_unblocked with scope: account. The older /accounts/{username}/firewall/blocked-ips routes are unchanged: they write the server firewall (scope: server).
Still Need Help?

Our support team is here around the clock for anything you can't find above.