Using WHM API tokens on a Managed VPS

On a Managed VPS with cPanel/WHM, the WHM API lets your scripts and apps manage the whole server: create and suspend cPanel accounts, change packages, check disk usage and more. Calls are authenticated with a WHM API token.

Caution

A WHM API token for root can control your whole server. Give each token only the permissions it needs, set an expiry date, and never put tokens in website code or public repositories.

Create a WHM API token

1. Log in to WHM. See Accessing WebHost Manager.
2. Search for Manage API Tokens (under Development).
3. Click Generate Token.
4. Enter a name, for example whmcs or monitoring.
5. Under Privileges, untick All Features and tick only what the token needs. For example, a monitoring script only needs List Accounts and View Account Information.
6. Optionally set an expiry date and limit the token to specific IP addresses that are allowed to use it.
7. Click Save, then copy the token. WHM shows it only once.

Make an API call

WHM API calls use port 2087, with the username and token in the Authorization header:

curl -H "Authorization: whm root:API_TOKEN" \
  "https://SERVER_HOSTNAME:2087/json-api/FUNCTION?api.version=1&PARAMETERS"

Examples

List all cPanel accounts:

curl -H "Authorization: whm root:API_TOKEN" \
  "https://SERVER_HOSTNAME:2087/json-api/listaccts?api.version=1"

Create a cPanel account:

curl -H "Authorization: whm root:API_TOKEN" \
  "https://SERVER_HOSTNAME:2087/json-api/createacct?api.version=1&username=newsite&domain=newsite.com&plan=default&contactemail=owner@newsite.com"

Suspend an account:

curl -H "Authorization: whm root:API_TOKEN" \
  "https://SERVER_HOSTNAME:2087/json-api/suspendacct?api.version=1&user=newsite&reason=Unpaid"

Check disk usage for all accounts:

curl -H "Authorization: whm root:API_TOKEN" \
  "https://SERVER_HOSTNAME:2087/json-api/get_disk_usage?api.version=1"

The full list is in the WHM API 1 documentation.

On the server itself

Scripts running on the VPS as root can use the whmapi1 command, with no token:

whmapi1 listaccts

Connecting billing software

Billing systems such as WHMCS use a WHM API token to create, suspend and terminate hosting accounts automatically. See Connecting WHM to WHMCS.

Revoke a token

In Manage API Tokens, click Revoke next to the token. It stops working immediately. Revoke and replace any token you think may have leaked.

Related articles

• Using cPanel API tokens to automate your hosting
• Managing web hosting accounts with WHM