WHMCS cPanel Integration: Setup, API Token and Common Errors

What does the built-in WHMCS cPanel module do?

It lets WHMCS create, suspend, unsuspend and terminate cPanel accounts, change their package or password, update usage figures and show a login link in the client area. The WHMCS cPanel module documentation lists those eight features. The server needs a valid cPanel & WHM license.

A WP Squared server needs the separate WP Squared module. Aim the cPanel module at one and WHMCS answers This module requires a cPanel & WHM server with a valid license and the 'Standard' server profile. It is not cPanel Extended For WHMCS either, which people also search for. That is a paid third-party module from ModulesGarden that puts cPanel functions inside the WHMCS client area.

What must be in place before you connect WHMCS to cPanel?

You need three things: open ports, a WHM package and two-factor authentication that does not block API requests.

• Ports 2086 and 2087 are open for outbound connections from the WHMCS server. WHMCS uses 2087 with SSL and 2086 without it.
• WHM has at least one package, created at Packages > Add a Package.
• If two-factor authentication is on in WHM, it is switched off for API requests. Log in as root, open Security Center > Configure Security Policies and untick API requests.

How do you create the WHM API token for WHMCS?

You create it in WHM at Development > Manage API Tokens with the Generate Token button. WHMCS accepts a WHM password or an API token. I use a token, because it can be limited to chosen privileges and to the IP address of the WHMCS server, and it can be revoked without changing the root password.

1. Click Generate Token and enter a name, up to 50 characters of letters, numbers, dashes and underscores.
2. Choose whether the token expires. An expiry date defaults to one year ahead, at 11:59:59 PM server time. An expired token stops working but is not deleted, so note the date or choose no expiry.
3. In the IPs box, enter the IP address of the WHMCS server. The field also takes CIDR ranges, up to 100 entries. A blank box lets any address use the token.
4. Under Privileges, untick everything that is not in the table below. At least one privilege has to stay ticked.
5. Click Generate and copy the token at once. WHM does not show it again.

The cPanel documentation on API tokens adds two cautions. It still calls privilege restrictions on tokens experimental. It also warns that Create User Session and Manage API Tokens let a token holder get around the restrictions you set, and WHMCS asks for both. Treat even a scoped token like a root password.

How do you add the cPanel server in WHMCS?

You add it at Configuration > System Settings > Servers with the Add New Server button.

1. Select cPanel for Module.
2. Enter the hostname or IP address, the WHM username and the API token.
3. Click Go to Advanced Mode for the other settings, such as the nameservers, Maximum No. of Accounts and the Secure checkbox.
4. Check the default port. If WHM listens elsewhere, tick Override with Custom Port and enter the real one.
5. Click Test Connection, wait for the success message, then click Save Changes.

WHMCS puts the nameservers in welcome emails and uses Maximum No. of Accounts to judge how full a server is. Secure turns on SSL. If this is your only cPanel server, click its name in the list and check that an asterisk appears. The asterisk marks the default server for the module.

How do WHM packages map to WHMCS products?

Each WHMCS product names one WHM package in its Module Settings tab. Open the product at Configuration > System Settings > Products/Services, choose Shared Hosting as the product type, set Module Name to cPanel and pick the plan in WHM Package Name. The name stored in WHMCS has to match WHM exactly, so a package renamed in WHM stops matching. The error is You do not have permission to use Selected Package.

• No package. Leave WHM Package Name empty, click Switch to Advanced Mode and type the limits. A blank field means unlimited.
• Reseller hosting. Choose Reseller Hosting as the product type, enter the limits in advanced mode and name an existing WHM ACL list in Reseller ACL List.

At the bottom of the tab, choose when WHMCS creates the account: when the order is placed, when the first payment is received, when you accept a pending order, or never automatically. For paid hosting I pick first payment.

How do server groups and fill rules work in WHMCS?

A server group is a set of servers that a product provisions onto, and its fill type decides which server gets the next account. Create one with Create New Group on the Servers page, then assign it to a product in the Module Settings tab. The server groups documentation gives two fill types.

• Add to the least full server, judged by the percentage of each server's Maximum No. of Accounts in use.
• Fill the default server until it reaches its account limit, then move to the next one.

Both rules count accounts, not disk space or load, so Maximum No. of Accounts is the only capacity figure WHMCS knows. One rule is easy to miss: with a single server in the group, pick the least-full fill type.

How does WHMCS sync disk and bandwidth usage from cPanel?

The daily cron run pulls disk space and bandwidth figures when Update Usage Statistics is ticked under Miscellaneous at Configuration > System Settings > Automation Settings. Utilities > Automation Status has a Server Usage Stats row that shows whether the last update succeeded. A server that is enabled in WHMCS but unreachable can make the update fail, so disable servers you have taken offline.

How does single sign-on from WHMCS to cPanel work?

Single sign-on lets a client or an admin open cPanel from WHMCS without typing the cPanel password. Three rules from the WHMCS single sign-on documentation explain most failures.

• A client user needs the View Products & Services and Perform Single Sign-On permissions.
• An admin can sign in to any account owned by the WHM user saved on the server. To limit that, edit the server, set Access Control to Restricted under SSO Access Control and choose the admin role groups allowed to use it.
• A reseller WHM user must own the account. If it does not, the result is Action Failed Unable to auto-login. Please contact support. The same message appears when the username on the service is empty.

How do you import existing cPanel accounts into WHMCS?

You import them with the Sync Accounts button on the Servers page. WHMCS fetches the account list from the server and shows a report, with differences in red and exact matches in green. What Import/Sync does depends on the row, according to the Sync Accounts documentation.

• On the server, not in WHMCS. WHMCS creates a service, using a matching product or creating a new one. It attaches the service to the client with the same email address, or creates a new client.
• Active in WHMCS, missing on the server. WHMCS sets the service to Terminated. If you wanted the account rebuilt instead, leave Import/Sync unticked on that row, then open the service and click Create under Module Commands.
• In both, with different details. WHMCS changes its own record to match the server. The documented fields are the domain, primary IP address, username, product, status and creation date.

The Activity Log at Configuration > System Logs lists what a sync changed.

Which errors appear when the WHMCS cPanel connection fails?

The usual messages are a cURL connection error, Login Failed and Access Denied. WHMCS documents a cause for each one.

For anything else, open Utilities > Module Queue, which lists failed module actions with the error text. The Module Log at Configuration > System Logs records what WHMCS sent and what WHM answered, but only after you set Module Logging to On. Set it to Off when you finish.

In words: if Test Connection fails, I fix the ports, the login or the token before anything else. If the package name differs between WHMCS and WHM, I make the names match. If the username is already on the server, I choose a free one. If a kept DNS zone blocks the domain, I delete the zone. If none of these applies, I read the Module Queue and the Module Log.

What are the limits and risks of the WHMCS cPanel integration?

Four things can hurt you: the token, Sync Accounts, failures nobody retries and kept DNS zones.

• The token is powerful. Restrict it to the IP address of the WHMCS server and revoke it when you replace it.
• Sync Accounts changes data. It can mark services Terminated and create products and clients. Take a database backup and read every row before you tick it.
• Failures wait for you. WHMCS does not retry a failed module action. It sits in the Module Queue until someone clicks Retry.
• A kept DNS zone blocks re-creation. If you tick Keep DNS Zone when terminating, you cannot create a new account for that domain on the server until the zone is deleted.