Provider guides
cPanel: configuration and operations
Create, suspend, unsuspend, terminate and change cPanel hosting accounts through the WHM API 1, with status sync and a read-only customer panel.
On this page
Status and workflow
The cPanel extension provisions cPanel hosting accounts through WHM API 1. It supports create with idempotent retry and reconciliation, status synchronization, suspension, unsuspension, termination, plan changes to an existing creatable package and a read-only customer panel with status, username, package and domain.
Production-ready for the documented scope. Every operation under Supported operations is implemented against the WHM API 1 specification and verified with automated tests that replace the provider with faked HTTP responses, without network calls. Live acceptance on your own WHM account remains an operator responsibility: create, suspend, unsuspend, change and terminate one disposable account on your own WHM server before you sell it. Operations under Not supported are not advertised.
Requirements
- Agovena Core
^0.0.1. - The Provisioning Module, enabled before this extension.
- A WHM server reachable over HTTPS, a WHM username (
rootor a reseller) and a WHM API token of that user. - At least one existing WHM package that the token may assign.
Set up the package
- Enable the Provisioning Module, then install and enable CPanel in Admin > Extensions.
- Save
api_urlasscheme://host:portonly, for examplehttps://server.example.com:2087. - Save
api_usernameand the WHM API token inapi_token. The token is encrypted at rest. - Keep
verify_tlsenabled. - Run Test connection. It makes the read-only
versioncall. - On each provisionable product, select this provider and set Package to an existing WHM package that the token may assign.
Supported operations
Every call is GET https://host:port/json-api/<function>?api.version=1 with the Authorization: whm header. A call succeeds only when metadata.command echoes the function and metadata.result is 1.
| Operation | WHM function | Parameters |
|---|---|---|
| Health check | version |
none |
| Package check on create and plan change | listpkgs |
want=creatable |
| Create | createacct |
username, plan, showpass=n |
| Reconcile an interrupted create | listaccts |
searchtype=user, searchmethod=exact, search |
| Status sync | accountsummary |
user |
| Suspend | suspendacct |
user, reason |
| Unsuspend | unsuspendacct |
user |
| Terminate | removeacct |
username |
| Change plan | changepackage |
user, pkg |
Status sync maps suspended 1 to suspended and 0 to active, and records the plan and domain. No customer password is sent, stored or returned; WHM generates one.
Not supported
- Customer power actions, single sign-on and password handover.
- A customer-chosen main domain. WHM assigns a temporary domain.
- Checkout capacity checks and moving an account between servers.
Failure handling and ownership
- Ownership is proven only by a row in
cpanel_accountsthat Agovena inserts before its owncreateacctcall. Accounts are never adopted fromprovider_mapping,external_ref, product settings or a lookup, and a service with such a reference but no claim row is refused without a network call. - Every lifecycle call requires the claim endpoint to match the current connection. A re-pointed server is refused without a network call. State changes run after the HTTP call as a compare-and-swap on
revision, so a concurrent change is never overwritten. - The username is
a, seven random lowercase characters and the base36 service ID, at most 16 characters. It is stored beforecreateacct, so a retry reuses it. A per-service lock serializes creates. metadata.result0or refused credentials mark the claimfailed. A retry checks the old username withlistaccts: clearly absent means a fresh username is claimed and created, present keeps the claimfailedfor manual review.- A timeout, HTTP error or malformed response marks the claim
unknown. The retry reads the stored username and accepts an existing account only when the owner, package and creation time match the claim. Anything else goes to manual review. - Terminate keeps the claim row as
terminated, so the username stays claimed. Tokens never appear in exceptions, logs, service meta or panel data.
Configuration contract
| Field | Type | Required | Secret | Default |
|---|---|---|---|---|
api_url |
string |
Yes | No | Empty |
api_token |
string |
Yes | Yes | Empty |
api_username |
string |
Yes | No | Empty |
verify_tls |
boolean |
No | No | true |
timeout |
string |
No | No | "20" |
api_url must be scheme://host:port without a path. Calls never follow redirects, verify TLS, pin DNS through the shared provisioning HTTP client and are refused in the demo environment. Production refuses plain HTTP and unverified TLS. Store secret values only in the protected extension settings, never in product descriptions, URLs, screenshots or shared examples.