# Using cPanel API tokens to automate your hosting

> Create a cPanel API token and use the cPanel API (UAPI) to automate tasks such as creating email accounts, listing databases and running backups from scripts and apps.

Source: https://helpcenter.ruachost.com/cpanel/advanced/using-cpanel-api-tokens/

The **cPanel API (UAPI)** lets scripts and apps do the same things you do in cPanel, without logging in: create email accounts, manage databases and domains, start backups and more. To use it from outside your hosting account, you need an **API token**. API tokens are available on every Ruachost hosting plan.

> **Caution:**
An API token gives **full access to your cPanel account**, like your password. Keep it secret: never put it in website code, public Git repositories, screenshots or support tickets. Give each token an expiry date, and delete tokens you no longer use.

## Create an API token

1. Log in to cPanel and open **Manage API Tokens** under **Security**.
2. Click **Create**.
3. Enter a **name** that says what it's for, for example `backup-script` or `n8n`. Use letters, numbers, dashes and underscores only.
4. Under **Expiration**, choose a date. A token without an expiry date works until you delete it.
5. Click **Create**.
6. **Copy the token now** and store it somewhere safe, such as a password manager. cPanel shows it only once.

## Make an API call

Every call is an HTTPS request to your server on port **2083**, with your cPanel username and token in the `Authorization` header:

```bash
curl -H "Authorization: cpanel CPANEL_USERNAME:API_TOKEN" \
  "https://SERVER_HOSTNAME:2083/execute/MODULE/FUNCTION?PARAMETERS"
```

Replace:

- `CPANEL_USERNAME` with your cPanel username. See [Finding your cPanel username](https://helpcenter.ruachost.com/cpanel/getting-started/finding-your-cpanel-username/).
- `API_TOKEN` with your token.
- `SERVER_HOSTNAME` with your server's hostname, shown in cPanel under **General Information** (**Server Name**), or in your welcome email.

The response is JSON. `"status": 1` means it worked; if not, `errors` explains why.

## Examples

**List your domains:**

```bash
curl -H "Authorization: cpanel CPANEL_USERNAME:API_TOKEN" \
  "https://SERVER_HOSTNAME:2083/execute/DomainInfo/list_domains"
```

**List email accounts:**

```bash
curl -H "Authorization: cpanel CPANEL_USERNAME:API_TOKEN" \
  "https://SERVER_HOSTNAME:2083/execute/Email/list_pops"
```

**Create an email account** (2048 MB quota):

```bash
curl -H "Authorization: cpanel CPANEL_USERNAME:API_TOKEN" \
  "https://SERVER_HOSTNAME:2083/execute/Email/add_pop?email=sales&domain=example.com&password=A-Strong-Password-123&quota=2048"
```

**List MySQL databases:**

```bash
curl -H "Authorization: cpanel CPANEL_USERNAME:API_TOKEN" \
  "https://SERVER_HOSTNAME:2083/execute/Mysql/list_databases"
```

**Create a full account backup** in your home directory, and email you when it's done:

```bash
curl -H "Authorization: cpanel CPANEL_USERNAME:API_TOKEN" \
  "https://SERVER_HOSTNAME:2083/execute/Backup/fullbackup_to_homedir?email=you@example.com"
```

The full list of modules and functions is in the [cPanel UAPI documentation](https://api.docs.cpanel.net/cpanel/introduction/).

## Running API calls on the server itself (no token needed)

Scripts that run **on your hosting account**, such as cron jobs or commands over SSH, can use the `uapi` command instead. It's already logged in as you, so no token is needed:

```bash
uapi --output=jsonpretty Email list_pops
```

For example, this [cron job](https://helpcenter.ruachost.com/cpanel/advanced/setting-up-cron-jobs-in-cpanel/) creates a full backup every Sunday at 2am:

```bash
0 2 * * 0 /usr/bin/uapi Backup fullbackup_to_homedir email=you@example.com > /dev/null 2>&1
```

Backups use disk space in your account, so download and delete old ones. Your account is also backed up automatically with JetBackup. See [Restoring files, email and databases using JetBackup](https://helpcenter.ruachost.com/cpanel/files/restoring-files-email-and-databases-using-jetbackup/).

## Using tokens with apps

Automation tools such as **n8n**, **Zapier** (Webhooks), **Make** or your own app can call the cPanel API. Use an **HTTP request** step with:

- **URL:** `https://SERVER_HOSTNAME:2083/execute/MODULE/FUNCTION`
- **Header:** `Authorization` = `cpanel CPANEL_USERNAME:API_TOKEN`

Store the token in the tool's credentials or secrets store, not directly in the workflow.

## Manage and revoke tokens

In **Manage API Tokens**, you can see each token's name, creation date and expiry. Click a token to **Revoke** it. Revoked tokens stop working immediately. If you think a token has leaked, revoke it straight away and create a new one.

## Troubleshooting

- **"Access denied" or 401:** check the username and token, and that the header starts with `cpanel ` followed by a space.
- **Connection times out:** check you're using port 2083 and the server hostname. Many failed attempts can block your IP address. See [My IP address is blocked](https://helpcenter.ruachost.com/getting-started/website-troubleshooting/my-ip-address-is-blocked/).
- **"The function … does not exist":** check the spelling and capital letters of the module and function names.

## Related articles

- [Dynamic DNS in cPanel](https://helpcenter.ruachost.com/cpanel/domains/using-dynamic-dns-in-cpanel/)
- [Using WHM API tokens on a Managed VPS](https://helpcenter.ruachost.com/vps/whm/using-whm-api-tokens/)