Manage API Tokens in WHM — Simple & Complete Guide

Manage API Tokens in WHM — Simple & Complete Guide

Manage API Tokens in WHM — Simple & Complete Guide

API tokens let you authenticate to WHM’s APIs without using a password. You can create multiple tokens, limit their permissions, and revoke them at any time. This guide covers creating, using, rotating, and removing tokens safely.

Important: Treat tokens like passwords. Anyone with a valid token can perform the actions you allow for that token.

Prerequisites

  • Access to WHM as root or a reseller with the right permissions.
  • Hostname with SSL if you will call APIs over HTTPS (recommended).
  • Know which permissions (scopes) the token should have.

Create a New API Token

  1. Sign in to WHM.
  2. Open Development → Manage API Tokens.
  3. Click Generate Token.
  4. Enter a name/label (for example, deploy-bot).
  5. (Optional) Set an expiration date.
  6. Select the permissions the token needs (least privilege).
  7. Click Save and copy the token once. You won’t be able to see it again.

Token Permissions (Least Privilege)

Tokens can be restricted to specific actions. Grant only what’s required, for example:

  • Accounts: create/terminate/suspend (admins only)
  • DNS: add/edit zone records
  • Packages: create or assign packages
  • SSL/TLS: install/manage certificates
  • Email: create mailboxes, forwarders, etc.

Use the Token (Examples)

Send requests over HTTPS and pass the token in the Authorization header.

cURL (JSON API Example)

curl -s \
  -H 'Authorization: whm root:YOUR_API_TOKEN' \
  'https://your-server.example.com:2087/json-api/version?api.version=1'

cURL (UAPI via WHM Proxy Example)

curl -s \
  -H 'Authorization: whm root:YOUR_API_TOKEN' \
  'https://your-server.example.com:2087/execute/Email/add_pop?domain=example.com&email=newuser&password=StrongPass123!'
Tip: Store tokens as environment variables in your CI/CD system and reference them securely (never hard-code tokens in scripts).

Rotate (Replace) a Token

  1. Create a new token with the same permissions.
  2. Update your scripts or integrations to use the new token.
  3. Test a few calls.
  4. Revoke the old token.

Revoke or Edit a Token

  1. Go to Development → Manage API Tokens.
  2. Find the token by label.
  3. Click Revoke to disable it immediately, or Edit to change its name, expiry, or permissions.

View Tokens & Audit

  • List shows token name, created date, last used, expiration, and status.
  • Use this page to audit unused or over-privileged tokens and clean them up regularly.

Security Best Practices

  • Use HTTPS only; block plain HTTP to the API ports.
  • Grant the minimum permissions needed (least privilege).
  • Set expirations where possible and rotate periodically.
  • Store tokens in a secrets manager (not in code repos).
  • Revoke tokens immediately if exposed or no longer needed.
  • Restrict API access by IP at your firewall where feasible.

Troubleshooting

  • 401/403 errors: Check token validity, permissions, and that you used the correct header format.
  • Hostname/SSL errors: Verify the URL, port (2087 for WHM over HTTPS), and certificate trust.
  • Action denied: The token likely lacks the required permission; edit the token or create a new one with the correct scope.

Summary

  • Create a token with a clear label, optional expiry, and least-privilege permissions.
  • Use the token via HTTPS with the Authorization header.
  • Rotate tokens safely and revoke any that are unused or exposed.
  • Audit tokens regularly and apply security best practices.
case studies

See More Case Studies