Automate cPanel Tasks Using UAPI, WHM API1, and Bash

Managing a single cPanel and WHM server is straightforward through the graphical web interface. But when you manage dozens—or hundreds—of accounts, manual tasks like provisioning new hosting packages, resetting user passwords, and auditing API tokens become major bottlenecks. Automation is the key to scaling your operations efficiently.

cPanel provides two powerful programmatic interfaces for automation: WHM API 1 for server-level administration (such as account creation) and UAPI for user-level tasks (such as password management and security auditing). In this guide, we will explore how to interact with these APIs directly from the Linux command line using curl and Bash scripts, allowing you to automate routine administrative chores on your server.

Understanding the Difference: WHM API 1 vs. UAPI

Before writing scripts, it is important to understand which API to use for a given task. cPanel architecture is divided into two distinct privilege levels:

• WHM API 1: This is designed for server administrators, resellers, and hosting providers. It operates with root-level or reseller privileges. You use WHM API 1 to perform high-level actions across the entire server, such as creating new cPanel accounts, terminating packages, or modifying server-wide configurations.
• UAPI: This is designed for individual cPanel account holders. It executes commands within the security context of a specific user. You use UAPI to manage email accounts, modify DNS zone records, manage MySQL databases, or handle security credentials for that specific account.

When authenticating with these APIs via curl, WHM API 1 requests are sent to port 2087 (the WHM secure port) using root credentials or an API token. UAPI requests are typically sent to port 2083 (the cPanel secure port) using the specific cPanel username and its corresponding credentials or token.

Generating and Securing WHM API Tokens

Hardcoding your root password into Bash scripts is a severe security risk. Instead, you should always use API tokens with restricted privileges. A WHM API token allows a script to authenticate without exposing your master password.

To generate an API token via the command line on an AlmaLinux 9 server running WHM/cPanel, you can use the WHM API 1 command-line tool, whmapi1, directly as the root user via SSH:

whmapi1 create_api_token token_name="AutomationScriptToken" acl-group=all

What this command does: Calls the WHM API 1 function create_api_token to generate a new token named "AutomationScriptToken" with the all Access Control List (ACL) group. For production environments, you should create custom ACL groups that only grant permissions for the exact tasks your script needs to perform.

Make sure to securely store the resulting token string. If the token is ever compromised, or when it is no longer needed, you must revoke it immediately to protect your server.

Automating cPanel Account Creation with WHM API 1

Provisioning a new hosting account programmatically is one of the most common automation tasks for web hosting providers and agencies. We can accomplish this using curl to send a POST request to the WHM API 1 endpoint.

The following Bash snippet demonstrates how to create a new cPanel account using an API token on AlmaLinux 9:

#!/bin/bash

# Configuration variables
WHMPORT="2087"
WHMUSER="root"
APITOKEN="YOUR_WHMPORT_API_TOKEN_HERE"
SERVER="localhost"

# New account details
NEWUSER="testclient"
DOMAIN="example.com"
PLAN="default"
EMAIL="client@example.com"

curl -s -k -H "Authorization: whm $WHMUSER:$APITOKEN" \
  "https://$SERVER:$WHMPORT/json-api/createacct?username=$NEWUSER&domain=$DOMAIN&plan=$PLAN&contactemail=$EMAIL" | grep -o '"result":1'

What this script does:

• Sets up variables for your WHM credentials, target server, and the new account details.
• Uses curl with the -s (silent) and -k (insecure SSL check, useful for self-signed local certificates) flags.
• Passes the API token securely in the HTTP Authorization header.
• Queries the createacct WHM API 1 endpoint with the required parameters (username, domain, hosting plan, and contact email).
• Pipes the JSON output into grep to verify if the creation was successful (indicated by "result":1).

Resetting cPanel Passwords via UAPI

Sometimes users forget their cPanel passwords, requiring administrators to intervene. While you can reset passwords via WHM, you can also automate this task using UAPI if you have root access to query user-level functions.

Here is how you can use curl and UAPI to update a user's password:

#!/bin/bash

WHMPORT="2087"
WHMUSER="root"
APITOKEN="YOUR_WHMPORT_API_TOKEN_HERE"
SERVER="localhost"

# Target cPanel account and new password
CPANELUSER="testclient"
NEWPASS="NewSecurePassword123!"

curl -s -k -H "Authorization: whm $WHMUSER:$APITOKEN" \
  "https://$SERVER:$WHMPORT/json-api/uapi?cpanel_jsonapi_user=$CPANELUSER&cpanel_jsonapi_module=Passwd&cpanel_jsonapi_func=passwd&security_code=$NEWPASS"

What this command does:

• Authenticates against WHM using your root API token, but targets a specific cPanel user by appending cpanel_jsonapi_user=$CPANELUSER to the UAPI endpoint wrapper.
• Calls the Passwd module and the passwd function via UAPI.
• Passes the new password securely via the query string parameter. (Note: In high-security environments, passing passwords via GET query parameters can expose them in server access logs; consider using POST data structures for production scripts).

Auditing and Revoking API Tokens

Security best practices dictate regular audits of API tokens. Stale or orphaned tokens left behind by former developers or deprecated automation scripts represent a significant security vulnerability.

You can list all active API tokens on the server using WHM API 1:

curl -s -k -H "Authorization: whm root:YOUR_WHMPORT_API_TOKEN_HERE" \
  "https://localhost:2087/json-api/list_api_tokens"

What this command does: Requests a complete JSON-formatted list of all API tokens configured on the WHM server, along with their associated users, creation dates, and token names.

Once you identify a compromised or obsolete token, you can revoke it immediately using the revoke_api_token function:

#!/bin/bash

WHMPORT="2087"
WHMUSER="root"
APITOKEN="YOUR_WHMPORT_API_TOKEN_HERE"
SERVER="localhost"

# Token name to revoke
TARGET_TOKEN="AutomationScriptToken"

curl -s -k -H "Authorization: whm $WHMUSER:$APITOKEN" \
  "https://$SERVER:$WHMPORT/json-api/revoke_api_token?token_name=$TARGET_TOKEN"

What this script does: Targets the WHM API 1 revoke_api_token endpoint, passing the exact name of the token to invalidate it instantly. Any subsequent scripts or services attempting to authenticate with that token will be blocked immediately.

Conclusion

Automating routine server administration tasks with cPanel's WHM API 1 and UAPI transforms how you manage your hosting environment. By moving away from manual web dashboard clicks and adopting Bash scripts powered by secure curl requests, you eliminate human error, speed up client onboarding, and maintain tight control over server security.

As you build out your automation toolkit, remember to always use API tokens instead of plaintext passwords, restrict token privileges to the bare minimum required, and regularly audit active credentials to keep your infrastructure secure and efficient.