If you've ever automated a backup check, a bulk account creation, or a DNS update with a script that logs into WHM using your root password in plain text, you've been carrying more risk than you need to. WHM API Tokens let you do the same automation without ever putting your actual account password in a script, a cron job, or a CI/CD secret store. Here's how to set one up properly, use it safely, and avoid the mistakes that get scripts blocked or tokens leaked.
Why Use an API Token Instead of a Password
A password gets you into everything: WHM, cPanel, email, DNS, the works. A token can be scoped down to exactly what a script needs — read-only DNS access, for instance — and revoked instantly the moment it's no longer needed, without touching your actual login credentials. If a token leaks in a git commit or a log file, you delete that one token. If your root password leaks, you're rotating it everywhere and wondering what else was compromised.
Tokens also don't expire your session the way password-based API calls sometimes do, and they show up cleanly in WHM's access logs under their own name, so you can tell "backup-script" from "dns-sync-job" when you're auditing what touched the server.
Creating a WHM API Token
This has to be done from WHM (port 2087), not cPanel — API tokens are a root/reseller-level feature.
- Log in to WHM as root or a reseller account.
- Go to Development → Manage API Tokens.
- Click Generate Token.
- Give it a specific name —
backup-monitor, nottoken1. You'll thank yourself later when you're deciding which one to revoke. - Set an expiration date if the token is for a one-off migration or short project. For an ongoing cron job, "Never Expire" is fine, but note it in your password manager so it doesn't get forgotten.
- Under ACL Setup, don't leave it on "all-acl" (full root access) unless the script genuinely needs everything. Pick a specific ACL list or create one that only allows the functions the script calls — for example, just
list-acctsanddomainuserdatafor a monitoring script. - Click Generate. WHM shows you the full token exactly once — copy it immediately into your secrets manager or an environment variable file. There's no way to view it again after you navigate away.
Using the Token With WHM API 1
Once you have the token, calls go through the same WHM API 1 (whmapi1) or UAPI endpoints, just with a different auth header. No cookies, no session negotiation.
curl -k "https://yourserver.example.com:2087/json-api/listaccts?api.version=1" \
-H "Authorization: whm root:YOUR_API_TOKEN_HERE"Notice the format: whm <username>:<token>, not just the raw token. That username has to match whichever account generated the token in step 1 above — a token generated under a reseller account won't authenticate as root.
For a DNS automation example — say a script that adds a new A record whenever a new client site goes live:
curl -k "https://yourserver.example.com:2087/json-api/cpanel?cpanel_jsonapi_user=clientuser&cpanel_jsonapi_apiversion=2&cpanel_jsonapi_module=ZoneEdit&cpanel_jsonapi_func=add_zone_record&domain=example.com&name=app.example.com.&type=A&address=203.0.113.10" \
-H "Authorization: whm root:YOUR_API_TOKEN_HERE"If you get Invalid Login Attempt back, double-check three things: the token wasn't retyped with a stray space, the username in the header matches the account that created the token, and the token hasn't been deleted or expired since you last used it.
Common Problems and Fixes
| Symptom | Likely Cause | Fix |
|---|---|---|
| 403 Forbidden on a specific function | Token's ACL doesn't include that function | Edit the ACL list attached to the token, or create a new list with the function added |
| Works from your laptop, fails from the server/cron | Firewall or CSF blocking outbound/inbound on port 2087 | Check csf -l or your firewall rules for port 2087; allow the source IP if calling from another server |
| Token stopped working overnight | Expiration date was set and quietly passed | Generate a new token, this time with "Never Expire" or a longer window if it's for a long-lived job |
| SSL certificate errors on the curl call | WHM's self-signed hostname cert doesn't match the connection hostname | Connect using the exact hostname on the WHM SSL certificate, not the server's bare IP |
| Rate limiting / connection resets on bulk calls | cPHulk or WHM's own throttling flagged rapid repeated calls | Add a short sleep between calls in loops, or check Security Center → cPHulk Brute Force Protection for blocked IPs |
Keeping Tokens Safe
Treat an API token exactly like a password, because functionally it is one:
- Never commit it to a git repository, even a private one — history doesn't forget, and private repos get forked or made public by accident more often than people expect.
- Store it in environment variables or a proper secrets manager (Vault, AWS Secrets Manager, even a locked-down
.envfile outside the web root), not hardcoded in the script itself. - Scope the ACL as tightly as the task allows. A monitoring script that only reads account status should never be able to suspend or terminate accounts.
- Review Manage API Tokens every few months and delete anything you don't recognize or no longer use. Old tokens from abandoned projects are a quiet liability.
- If you ever suspect a token leaked — a log got shared, a repo went public, a former contractor still has access — delete it in WHM immediately and generate a fresh one. Deletion takes effect instantly; there's no grace period to worry about.
When to Reach for This
API tokens make the most sense for repeatable, unattended tasks: nightly account audits, DNS record sync between systems, provisioning new hosting accounts from an order form, pulling bandwidth stats into a billing dashboard, or feeding uptime data into your own monitoring stack. If you're only running a command by hand once a quarter, a scoped API token is still safer than typing your root password into a curl command on your terminal history — but the real payoff shows up once a script is running unattended on a schedule where nobody's there to notice if the credential leaked.
Frequently Asked Questions
Can a cPanel user (not root/WHM) create an API token?
Yes — cPanel itself has its own API Tokens page under Security → Manage API Tokens in the cPanel interface, separate from WHM's. Use that one for scripts that only need to act within a single cPanel account rather than across the whole server.
Do API tokens work with UAPI as well as WHM API 1?
Yes. The same Authorization: whm user:token or Authorization: cpanel user:token header (for cPanel-level tokens) works across whmapi1, cPanel API 2, and UAPI calls — you don't need a separate token per API style.
What happens to running scripts if I delete a token mid-use?
The very next API call using that token fails immediately with an authentication error. There's no grace period, so if you're rotating a token used by a live cron job, generate and deploy the replacement first, confirm it works, then delete the old one.
Is there a limit to how many tokens I can create?
WHM doesn't impose a hard cap in most current versions, but keeping the count low and each token named and scoped clearly matters far more for security than any technical limit does.
Can I restrict a token to a specific IP address?
WHM's token generator itself doesn't have a per-token IP allowlist field, but you can achieve the same result with your firewall (CSF, iptables, or a cloud security group) by only permitting port 2087 connections from the known IPs that run your scripts.
