# Using WHM API tokens on a Managed VPS

> Create a WHM API token on your Ruachost Managed VPS, limit what it can do, and use the WHM API to automate account creation, monitoring and backups.

Source: https://helpcenter.ruachost.com/vps/whm/using-whm-api-tokens/

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](https://helpcenter.ruachost.com/vps/whm/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:

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

## Examples

**List all cPanel accounts:**

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

**Create a cPanel account:**

```bash
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:**

```bash
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:**

```bash
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](https://api.docs.cpanel.net/whm/introduction/).

## On the server itself

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

```bash
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](https://helpcenter.ruachost.com/vps/whm/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](https://helpcenter.ruachost.com/cpanel/advanced/using-cpanel-api-tokens/)
- [Managing web hosting accounts with WHM](https://helpcenter.ruachost.com/vps/whm/managing-web-hosting-accounts-with-whm/)