Connect Blesta to cPanel/WHM for automatic account provisioning

A Blesta install without working provisioning is just an invoicing tool. The cPanel module is what closes the loop — order paid, account created on WHM, welcome email out, all without a human typing whoami. It ships with Blesta core, but getting it from "installed" to "actually creating accounts" takes more than ticking a checkbox: the API token needs the right scopes, the package needs to point at a WHM plan that exists, and the nameserver fields have to be set or every welcome email goes out with ns1.your-domain.com placeholders.

This guide assumes you have Blesta 5.x running and a cPanel/WHM box you control as root. If you're still picking between Blesta and WHMCS, the 2026 comparison covers the trade-offs first.

Prerequisites

• Blesta 5.6 or later on a publicly reachable host with a valid Blesta licence.
• A cPanel/WHM server you can SSH into as root, with a current cPanel licence.
• The WHM box reachable from Blesta on TCP 2087.
• A WHM package (cPanel → Packages → Add a Package) that defines the disk, bandwidth, and feature list customers will receive. The package name is the string Blesta will reference — note it exactly, including any reseller prefix.
• The nameserver hostnames you want clients to use (e.g. ns1.example-hosting.com), and matching A records that already resolve to the WHM box.

Step 1 — Create a scoped WHM API token

Don't use root password authentication or the root account's full-access token. Create a dedicated token with only the privileges Blesta needs, so a compromised Blesta install can't wp-toolkit its way through the whole server.

In WHM go to Development → Manage API Tokens → Generate Token:

• Token name: blesta-provisioning
• Privileges: tick the following and nothing else:
  • create-acct
  • removeacct
  • suspendacct
  • unsuspendacct
  • passwd
  • changepackage
  • editquota
  • listaccts
  • accountsummary
  • domainuserdata
  • cpanel (needed for cPanel-side API calls through WHM, e.g. mailbox creation)

Click Save. Copy the token — WHM shows it once, never again. If you miss it, revoke and regenerate.

Step 2 — Install the cPanel module in Blesta

In Blesta admin go to Settings → Company → Modules → Available, find cPanel, and click Install. The module is bundled with Blesta core — no marketplace download.

The cPanel module supports two service types out of the same install: shared accounts (the common case) and reseller accounts (for sub-resellers). The choice happens at the package level later; the module itself doesn't need switching.

Step 3 — Add the server in Blesta

Go to Settings → Company → Modules → cPanel → Manage → Add Server.

Fill in:

• Server Label: a human-readable name, e.g. wm01-uk-london. This appears in admin lists and welcome emails as %server_name% if you reference it in templates.
• Hostname: the WHM hostname, e.g. wm01.example-hosting.com. Must resolve from the Blesta server — dig +short wm01.example-hosting.com from the Blesta box should return the right IP.
• Username: root (or the reseller username if you scoped the token to a reseller).
• Use SSL when connecting: tick. Always.
• Account Password: leave blank.
• API Key: paste the token from step 1.
• Use SSL when connecting to the API: tick.
• Name Servers: enter the two (or more) nameserver hostnames you want assigned to new accounts. Blesta passes these to WHM's create-acct and they end up on the account's DNS zone.

Click Test Connection before saving. A green tick means the token authenticates and listaccts returned. Red usually means one of three things:

• DNS doesn't resolve — fix on the Blesta host
• Port 2087 blocked — check CSF/firewall on the WHM box
• Token has insufficient privileges — regenerate with the list in step 1

Save when the test passes.

Step 4 — Create a Server Group

Even with one server, the module wants a group. Server groups are how Blesta load-balances and how packages reference upstream capacity.

In cPanel → Manage → Server Groups, click Add Group:

• Group Name: Shared UK
• Add Order: First non-full server is the right default. With one server it doesn't matter; with five it spreads new accounts to whichever isn't at its limit.

Add the server you created in step 3 to the group. Save.

Step 5 — Create the package

A Blesta package is the product customers buy. It binds a price (and currency, billing cycle, etc.) to a module and a server group, and tells the module which WHM package to use.

Go to Packages → Browse → Add Package:

• Module: cPanel
• Module Group: the group from step 4
• Module Row: leave on Auto
• Package: pick the WHM package name from the dropdown. Blesta populates this list by calling listpkgs against the server — if it's empty, the token doesn't have listpkgs privilege (add it and retest).
• ACL: leave blank for shared, set for reseller packages
• Type: Standard for shared, Reseller for sub-reseller WHM accounts
• Use Domain Name: tick. This makes the order form ask for a domain, which becomes the cPanel account's primary domain. Without it, you'll need to add a custom configurable option called domain, which is more work.

In the Pricing tab, set monthly/annual prices and the currency. The currency must match a configured payment gateway — see the Stripe Payments setup or PayPal Standard setup if you haven't wired one yet.

In the Welcome Email tab, leave the default template or customise. Available tags include %username%, %password%, %ip_address%, %name_servers%, and %cpanel_url% — these get populated from the WHM response after the account is created.

Save the package and mark it Active.

Step 6 — Place a test order

Log in as a client (or use Clients → Add Client then Order Service), go through the order flow for your new package, and pay with a test transaction (or mark the invoice paid manually as admin).

Within a few seconds of payment confirmation, Blesta calls create-acct on WHM. To watch it happen:

tail -f /usr/local/cpanel/logs/error_log

You should see entries like Account Creation Ok followed by the username and primary domain. In Blesta, the service status flips from Pending to Active and the welcome email goes out.

If the service stays Pending, check Tools → Logs → Module in Blesta. The most common errors:

• username already exists — Blesta generates the username from the domain; collisions happen with duplicate domains
• account creation failed: this domain is already configured — same domain is on another account, on this server or in DNS clusters
• Access denied for user 'root'@'...' — API token rejected; usually privilege missing or token revoked
• timeouts — DNS resolution slow, or WHM tarpitted the connection (check /var/log/secure on WHM for IP-based block)

Step 7 — Suspension, termination, and password changes

Once provisioning works, the rest of the lifecycle wires up automatically:

• Non-payment suspension — when an invoice ages past the grace period in Settings → Company → Billing → Late Fees and Suspension, Blesta calls suspendacct. The cron must be running for this; see Blesta cron setup if you skipped that step.
• Cancellation — when a client cancels and the service date passes, Blesta calls removeacct. The cPanel account is destroyed and the home directory is moved to /home/cpmove-<user>.
• Upgrade/downgrade — when a client changes package, Blesta calls changepackage to apply the new WHM package.
• Password change — from the client area or admin, Blesta calls passwd. Doesn't reset email mailbox passwords by default — that needs the FTP-Maildir password sync option enabled in the package settings.

Common failure modes after go-live

Welcome emails arrive with no password. The %password% tag is empty because the package has Send Initial Password unticked. Re-tick it in the package and resend.

New accounts get ns1.your-domain.com-style nameservers. Nameserver fields on the server (step 3) were left as the example placeholders. Edit the server, set the real NS hostnames, save. Existing accounts keep the wrong ones — fix them with whmapi1 setdns domain=example.com nameservers=ns1.real.com,ns2.real.com.

Reseller orders create shared accounts instead. Package Type is set to Standard. Change to Reseller and set an ACL list in the package, otherwise WHM creates the account but doesn't grant reseller privileges.

Provisioning works in test mode, fails in production. Almost always cPanel's cPHulk brute-force protection blocking the Blesta IP after repeated successful logins look like password-guessing. Whitelist the Blesta server's IP in WHM → Security Center → cPHulk Brute Force Protection → White/Black List Management.

Service status stuck on "Pending" but the cPanel account exists. Blesta sent the create call, WHM created the account, but the API response was truncated or timed out before Blesta logged success. Manually mark the service Active in Blesta, then look at journalctl -u cpanel for the timeout cause — usually a slow DNS cluster sync. See cPanel DNS cluster on a DNSONLY box.

Next steps

• Wire up payments so the order-to-provisioning flow runs end-to-end: Stripe Payments setup or PayPal Standard.
• Run the Blesta cron so suspensions, terminations, and renewal invoices fire on schedule.
• Activate or renew your Blesta licence before going live with paying customers.