KoaVM
Guide pages

Guide · For administrators

API and integrations

API keys

In Settings › API › Create key name the key (e.g. "WHMCS"). The key, kvm_…, is shown only once: copy it right away. Each key acts as the administrator who created it; keep it on the billing server, never in the browser. Revoke it from the same page.

Calls go to https://vm.yourdomain.com/api/v1/… with the header Authorization: Bearer kvm_…. Limit: 600 requests per minute per key.

Main calls

CallWhat it does
GET /pingtests the key
GET /plans, GET /images, GET /locationsplans, operating systems, nodes and zones
GET /clients?email=…, POST /clientsfind or create a customer
POST /vpscreate a VPS
GET /vps/{id}, GET /vps?external_id=…VPS status
POST /vps/{id}/powerstart, stop, restart
POST /vps/{id}/suspend, /unsuspendsuspend (with a reason) and reactivate
POST /vps/{id}/planplan change (restart: true to apply it now); with extra and extra_disk_gb also extra resources and an additional disk
POST /vps/{id}/resourcescustom resources: vcpu, ram_mb, disk_gb (up only), net_mbit, traffic_gb
GET/POST /vps/{id}/disks, PUT/DELETE /vps/{id}/disks/{disk}extra disks: list, add (size_gb, mount), grow, remove (?confirm=disk1)
PUT /vps/{id}/ipsextra IPs: {"count": 3} makes the VPS have exactly 3 (for billing)
POST /vps/{id}/ips, DELETE /vps/{id}/ips/{ip}adds extra IPs (count or ips), removes one
POST /vps/{id}/password, /reinstallnew password, reinstall
GET /vps/{id}/usagemonthly traffic and disk
POST /vps/{id}/login-linksign-in link for the customer
DELETE /vps/{id}delete

Creation example:

curl -X POST https://vm.yourdomain.com/api/v1/vps \
  -H "Authorization: Bearer kvm_…" -H "Content-Type: application/json" \
  -d '{"client":{"email":"mario@example.com","name":"Mario Rossi"},"plan_id":1,
       "image":"debian/12/cloud","hostname":"web1.example.com","external_id":"order-1001"}'

To sell extra resources add "extra": {"vcpu": 1, "ram_mb": 2048, "disk_gb": 20} (added to the plan), "extra_disk_gb": 100 for an additional disk mounted on /mnt/disco1 and "extra_ips": 2 for two extra IPs taken from the node's routed blocks (listed in the VPS's extra_ips).

With external_id (or the Idempotency-Key header) the same request repeated does not create duplicates: it returns the VPS already created. The response contains the root password and, for a new customer, their password.

One-click sign-in

POST /vps/{id}/login-link returns a single-use link, valid for 2 minutes, that opens the VPS page already signed in. Once used it expires: the customer sees the sign-in page with a notice.

WHMCS

Download the module from Settings › API › Download the WHMCS module and copy modules/servers/koavm into the WHMCS folder. Then:

  1. Setup › Products/Services › Servers › Add New Server: panel hostname, module KoaVM, the kvm_… key as password, Secure on. Test Connection must answer "successful".
  2. In the product (Server/VPS type), Module Settings tab: KoaVM module, plan, default operating system, location (empty = automatic).
  3. Optional: configurable options Operating System and Location, custom field SSH Key.
  4. To sell extra resources: configurable options Extra RAM (GB), Extra vCPU, Extra disk space (GB), Additional disk (GB) and Additional IPs (they go in the service's assigned IPs).

The module handles creation, suspension, reactivation, termination, package change, password, start and stop, one-click sign-in to the panel and disk and traffic usage. The README in the zip explains everything in detail.

Koabilling

In Koabilling add the KoaVM provider with the panel address and the API key. In the product: plan = KoaVM plan id, region = node or zone id (empty = automatic), image = system (e.g. debian/12/cloud).