WHMCS integration security

Security controls for the API-only link between WHMCS and HexaHost GameCloud.

Trust model

WHMCS is the commercial system of record (payments, invoices)
GameCloud is the technical system of record (servers, nodes)
Integration is one-way authenticated API — no shared database

Authentication layers

1. HMAC request signing (required)

Every request to /api/v1/integrations/whmcs/* includes:

Header	Purpose
`X-HGC-Integration-Id`	Installation identifier
`X-HGC-Timestamp`	Unix epoch seconds
`X-HGC-Signature`	HMAC-SHA256 of canonical request

Secret: WHMCS_API_SECRET — rotate via secrets.

Clock skew tolerance: ± 300 seconds. Sync NTP on both hosts.

2. mTLS (production recommended)

When INTEGRATION_MTLS_ENABLED=true:

Client certificate required from WHMCS host
Fingerprint registered in GameCloud installation record
See mtls

3. Network controls

Allowlist WHMCS egress IP at firewall or Traefik
No public exposure of WHMCS admin URL without 2FA
API only on HTTPS (api.example.net)

WHMCS hardening

Control	Recommendation
Admin 2FA	Required for all staff
File permissions	Module PHP not writable by web user
API Secret storage	WHMCS encrypted settings storage
Module logs	Restrict Utilities → Logs access
Hooks file	`includes/hooks/hexagamecloud.php` owned by root/deploy user

Least privilege

WHMCS server module credentials are not stored in WHMCS server username/password fields — only in addon encrypted settings. GameCloud API keys for customers are separate from integration secret.

Audit

GameCloud logs integration calls with integration ID and action. WHMCS module log redacts secrets. Correlate by timestamp and externalServiceId.

Incident response

On suspected secret leak:

Rotate WHMCS_API_SECRET on GameCloud first, then WHMCS addon
Review module log for anomalous provisioning
Run reconciliation dry-run
Re-register mTLS fingerprint if cert compromised

See incident response.

Compliance

PCI: WHMCS handles card data; GameCloud never receives PAN
GDPR: Customer PII flows in upsertClient — subject to data retention

2.5 KiB Raw Permalink Blame History