WHM API 1 is cPanel's programming interface to WHM (Web Host Manager). It lets a reseller or server administrator create, suspend and remove cPanel accounts, manage hosting packages and DNS zones, and read server information from a script instead of clicking through WHM. This guide explains who can use it, how to authenticate safely, and the functions you are most likely to need, with correct syntax.
WHM API 1 is for people who log in to WHM: cPanel resellers and owners of a server with WHM. Resellers call it over HTTPS on port 2087 with an API token (Authorization: whm USERNAME:TOKEN) and can act only on the accounts they own; the whmapi1 command-line tool needs root on the server. If you have a single cPanel hosting account, you don't have WHM, so use cPanel's own API, UAPI, on port 2083 instead.
1. Which API is yours?
cPanel has two current APIs, and the one you can use depends on the login you have:
| Your account | Panel you log in to | API to use | Port |
|---|---|---|---|
| Shared cPanel hosting | cPanel | UAPI | 2083 |
| cPanel reseller hosting | WHM (and cPanel for your own sites) | WHM API 1 for your client accounts; UAPI inside each cPanel account | 2087 and 2083 |
| A server you run with cPanel and WHM installed | WHM as root | WHM API 1, plus the whmapi1 command line | 2087 |
Older tutorials also mention cPanel API 1 and API 2. Those are legacy; use UAPI for anything new.
2. Authenticate with an API token
API tokens are the right way to authenticate. Don't put your WHM password in a script, and don't use the old "access hash", which cPanel has deprecated.
- Log in to WHMand search for Manage API Tokens (under Development).
- Click Generate Token, give it a descriptive name such as
billing-sync, and choose only the privileges the script needs, if your WHM offers that choice. - Copy the token straight away.WHM shows it once.
- Store itin your script's configuration or a secrets manager, never in a public repository.
Every request then sends this header:
Authorization: whm USERNAME:TOKENUSERNAME is your WHM login (your reseller username, or root on your own server). Note the word whm: the cpanel prefix is for cPanel and UAPI tokens and won't work on port 2087.
Anyone holding the token can create, suspend or delete your client accounts. Give each script its own token, revoke tokens you no longer use (api_token_revoke, or Manage API Tokens in WHM), and change a token immediately if it may have leaked.
3. Make your first call
Over HTTPS, every WHM API 1 call has the same shape. Include api.version=1, or WHM may answer in an older format:
curl -s -H "Authorization: whm USERNAME:TOKEN" \
"https://your-server-hostname:2087/json-api/listaccts?api.version=1"Parameters go in the query string, URL-encoded:
curl -s -H "Authorization: whm USERNAME:TOKEN" \
"https://your-server-hostname:2087/json-api/accountsummary?api.version=1&user=clientuser"The reply is JSON with a metadata block. Check metadata.result: 1 means success, 0 means failure, and metadata.reason says why. An HTTP 200 alone doesn't mean the action worked.
On your own server as root, the same functions run from the shell without a token:
whmapi1 --output=jsonpretty listacctsResellers on shared infrastructure don't have root, so they use the HTTPS form.
4. Account functions
These are the calls resellers use most. Each acts only on accounts you own; asking about another account returns an access error.
| Task | Function | Key parameters |
|---|---|---|
| List your accounts | listaccts | optional search, searchtype=domain or user |
| One account's details | accountsummary | user |
| Create an account | createacct | username, domain, plan, password, contactemail |
| Suspend | suspendacct | user, reason |
| Unsuspend | unsuspendacct | user |
| Change package | changepackage | user, pkg |
| Change password | passwd | user, password |
| Change disk quota | editquota | user, quota (MB) |
| Show bandwidth use | showbw | optional search, month, year |
| Remove permanently | removeacct | username (older scripts use user) |
Creating an account from a script:
curl -s -G -H "Authorization: whm USERNAME:TOKEN" \
"https://your-server-hostname:2087/json-api/createacct" \
--data-urlencode "api.version=1" \
--data-urlencode "username=client1" \
--data-urlencode "domain=client1-example.com" \
--data-urlencode "plan=USERNAME_starter" \
--data-urlencode "password=A-Long-Random-Password" \
--data-urlencode "[email protected]"-G with --data-urlencode builds a correctly encoded query string, which matters for passwords containing &, + or #. The plan must be a package you created; reseller packages are usually prefixed with your username.
There is no recycle bin. Take a backup first, and have your script ask for confirmation, or require a second flag, before it calls removeacct.
5. Packages, DNS and email functions
| Area | Function | What it does |
|---|---|---|
| Packages | listpkgs | Lists the packages you can assign |
| Packages | addpkg / editpkg | Creates or edits a package (name, quota, bwlimit, maxpop, maxsql and more) |
| Packages | killpkg | Deletes a package (pkgname) |
| DNS | listzones | Lists the DNS zones you control |
| DNS | dumpzone | Returns every record in a zone (domain) |
| DNS | addzonerecord / editzonerecord / removezonerecord | Adds, changes or deletes one record; edits and deletes take the record's line number from dumpzone |
| DNS | adddns / killdns | Creates or deletes a whole zone |
suspend_outgoing_email / unsuspend_outgoing_email | Stops or restores outgoing mail for one account (user) |
Always read dumpzone again before editzonerecord or removezonerecord. Line numbers shift when records are added or removed, so an old line number can change or delete the wrong record.
6. Server-level functions
Most of these need root, or privileges a reseller account usually doesn't have. They matter mainly if you run your own server:
| Function | What it does |
|---|---|
setupreseller / setresellerlimits / listresellers | Creates resellers and sets their limits |
suspendreseller / unsuspendreseller | Suspends a reseller and all its accounts |
resellerstats | Summarises a reseller's accounts and usage |
version / gethostname / systemloadavg | Server version, hostname and load |
servicestatus / restartservice | Checks or restarts a service such as httpd or exim |
php_get_installed_versions / php_get_vhost_versions / php_set_vhost_versions | Lists PHP versions and sets one per site |
installssl | Installs a certificate for a domain |
Many functions listed in older guides don't exist in WHM API 1, for example createrepo, restorepkg, terminateacct, createdb, listdbs, addpop and list_pops. Databases and mailboxes belong to a cPanel account, so manage them with UAPI inside that account.
7. UAPI for cPanel account holders
If you have a single cPanel hosting account, UAPI does for your account what WHM API 1 does for a server. Create a token in cPanel under Security › Manage API Tokens, then call:
curl -s -H "Authorization: cpanel CPANEL_USERNAME:TOKEN" \
"https://your-server-hostname:2083/execute/DomainInfo/list_domains"The URL pattern is /execute/Module/function, with parameters in the query string. Two examples:
# List your MySQL databases
curl -s -H "Authorization: cpanel CPANEL_USERNAME:TOKEN" \
"https://your-server-hostname:2083/execute/Mysql/list_databases"
# Create a database (the name must start with your cPanel username and an underscore)
curl -s -H "Authorization: cpanel CPANEL_USERNAME:TOKEN" \
"https://your-server-hostname:2083/execute/Mysql/create_database?name=CPANEL_USERNAME_shop"UAPI replies with status (1 or 0), errors and data. Your cPanel username, server IP and panel address are in your client area, on the hosting service's Manage › Access tab.
8. Good practice for automation
- Least privilege. One token per script, limited to the privileges it needs where WHM allows it.
- Check the result field on every call, and log
metadata.reasonorerrorswhen it fails. - Go easy on the server. Space out bulk jobs and don't poll every few seconds; repeated rapid requests can be slowed down or blocked.
- Test on one account before running a loop over all of them.
- Keep tokens off the command line on shared machines: other users can see running processes. Read them from a file only you can read.
9. Where Domain India fits
Domain India's cPanel reseller hosting gives you WHM to create and manage your own clients' cPanel accounts, so WHM API 1 over HTTPS on port 2087 is available to you with a token, within your reseller privileges. Shared cPanel hosting gives you cPanel, where UAPI and API tokens are available. On our shared and reseller servers you don't have root, so the whmapi1 command line isn't available. Jailed SSH access is available on every shared hosting plan (cPanel, DirectAdmin, Webuzo); it is off by default and support enables it on request, but it doesn't give you WHM functions.
Backups on our cPanel servers are handled by JetBackup, which takes weekly account backups that you can download or restore from JetBackup in the panel. There is no backup function to script through WHM API 1.
If an API call returns an access error you think you should have, open a ticket with the function name and the exact reason text, but never the token.
Frequently asked questions
What is WHM API 1?
It is cPanel's programming interface to WHM. Resellers and server administrators use it to create, suspend and remove cPanel accounts, manage packages and DNS zones, and read server information from scripts.
Can I use WHM API 1 with a shared cPanel hosting account?
No. A shared hosting account has cPanel, not WHM. Use UAPI instead, with a token from Manage API Tokens in cPanel, at https://your-server-hostname:2083/execute/Module/function.
How do I authenticate to WHM API 1?
Create an API token in WHM under Manage API Tokens and send the header "Authorization: whm USERNAME:TOKEN" with each HTTPS request to port 2087. Don't use your password or the deprecated access hash.
Can a reseller use the whmapi1 command?
Not on shared infrastructure. The whmapi1 command-line tool needs root on the server. Resellers call the same functions over HTTPS on port 2087 with an API token.
Why does my WHM API call return HTTP 200 but nothing changed?
Check metadata.result in the JSON reply. A value of 0 means the call failed, and metadata.reason explains why, for example a missing parameter or no access to that account.
Can a reseller manage accounts owned by someone else?
No. WHM API 1 lets a reseller act only on the accounts that reseller owns. Calls about any other account return an access error.
How do I create a MySQL database or mailbox through the API?
Use UAPI inside the cPanel account that owns it, for example Mysql/create_database. WHM API 1 has no general function for creating databases or mailboxes.
Ready to automate your hosting business? Compare reseller hosting plans, see cPanel hosting, or ask us in a support ticket.
Create and manage your clients' cPanel accounts from WHM, by hand or through the API.
See reseller hosting