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.
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.normpathand matrix-param stripping (so trailing;foo=barcannot 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)
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.
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.
Client sign-in links (billing systems)
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'sReferer. The page the link opens reads the token, removes it from the address bar and posts it toPOST /api/v1/auth/client/login-token(form fieldtoken). 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 session403 PERMISSION_DENIED; an account-bound or restricted key403 SCOPE_DENIED. -
Links live in the agent's memory: an agent restart drops the unused ones. With an
X-Idempotency-Key, a replay returnslogin_urlas"***"— 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
dbthe account does not hold, answers404 DATABASE_NOT_FOUNDbefore any MariaDB user is created; another account's database name is read as a name inside this account. - A used token answers
401on 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 answers200witherror_code: PMA_NOT_INSTALLED. - The per-database route
GET /accounts/{username}/databases/{db_name}/phpmyadmin-urlkeeps 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/24is stored as203.0.113.0/24. An address already on the list answers200unchanged. Unspecified, multicast, link-local and/0values, a wider network, control characters in the note and unknown fields answer422 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 answers404 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 answer409 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_unblockedwithscope: account. The older/accounts/{username}/firewall/blocked-ipsroutes are unchanged: they write the server firewall (scope: server).
Our support team is here around the clock for anything you can't find above.