Skip to main content

Billing System API Tokens

Overview​

When you connect an external billing system (WHMCS, Blesta, HostBill, or anything that talks to the platform's billing API) it needs a way to authenticate its requests. That is what a billing API token is: a long secret string the external system attaches to every API call, plus a stored record on the Master that ties the token to a specific source IP.

Tokens are generated, listed, enabled, disabled and removed from the management server's shell using the hvcli api:billing-token command. The token's secret value is shown exactly once, at creation time, and is never recoverable afterwards.

Concepts​

  • A token is a UUID-keyed record stored on the Master. Each token has a name, an optional description, the source IP it is bound to, and an enabled/disabled flag.
  • The token ID (a UUID) is what you use to enable, disable or remove a token later. The token itself (the actual secret) is shown only at creation time.
  • An IP-bound token is rejected if it arrives from any IP other than the one it was created for. This means a leaked token cannot be used from an attacker's server.

Admin steps​

Generate a new token​

SSH into the management server and run:

hvcli api:billing-token generate

You will be prompted for:

  • IP Address: the public IP of the billing system that will use this token (for example, your WHMCS server's IP).
  • Name: a label for your own reference, for example WHMCS-Production.
  • Description: optional free text.

Sample output:

Success! Your new API token:
Token ID: 550e8400-e29b-41d4-a716-446655440000
Token: *********

WARNING: This token will NEVER be shown again!

Copy the Token value into the billing system's configuration immediately. If you lose it, you have to generate a new token; there is no recovery flow.

List existing tokens​

hvcli api:billing-token list

Sample output:

+--------------------------------------+------------------+---------------------+----------------+---------+
| ID                                   | Name             | Description         | IP Address     | Enabled |
+--------------------------------------+------------------+---------------------+----------------+---------+
| 550e8400-e29b-41d4-a716-446655440000 | WHMCS-Production | Primary integration | 203.0.113.45   | Yes     |
| 3d8d8e80-2b97-11ed-a261-0242ac120002 | Backup-System    | Failover server     | 198.51.100.10  | No      |
+--------------------------------------+------------------+---------------------+----------------+---------+

The ID column is what you pass to enable, disable or remove commands.

Enable, disable or remove a token​

# Enable a previously disabled token
hvcli api:billing-token enable 550e8400-e29b-41d4-a716-446655440000

# Temporarily turn a token off without deleting it
hvcli api:billing-token disable 550e8400-e29b-41d4-a716-446655440000

# Delete a token permanently
hvcli api:billing-token remove 550e8400-e29b-41d4-a716-446655440000

Disabled tokens are kept in the list but every API call using them is rejected.

Security best practices​

  1. Store the token in the billing system's encrypted credentials store, not in plain text files.
  2. Always set an IP restriction; never leave the IP blank.
  3. Rotate tokens every 6-12 months. Generate a new one, swap it in the billing system, then remove the old one.
  4. Disable immediately if a token may have leaked; investigate before removing.