Un'API REST per collegare KoaPanel a qualunque sistema

In breve

La chiave API

Nel pannello, come amministratore o rivenditore: Chiavi API › Crea chiave. La chiave (kpk_…) si vede una sola volta e agisce come il suo account:

• la chiave di un rivenditore vede e modifica solo i propri clienti e pacchetti, entro la sua quota;
• per creare rivenditori serve la chiave di un amministratore;
• se l'account viene sospeso o eliminato, le sue chiavi smettono di funzionare;
• ogni operazione compare nel Registro attività con il nome della chiave.

Cosa si può fare

L'elenco completo con tutti i campi è nel documento OpenAPI del server.

Esempi

curl

export KP=https://server1.example.com:8443/api/v1
export KEY=kpk_...   # Chiavi API › Crea chiave

# un account con la password scelta dal tuo sistema, sicuro da ripetere
curl -sS -X POST "$KP/accounts" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-10452" \
  -d '{"username":"mario","email":"mario@example.com","package":"pkg_base","passwordMode":"set","password":"Una-Password-Robusta-2026"}'

# sospensione per fattura scaduta, poi riattivazione
curl -sS -X POST "$KP/accounts/mario/suspend" -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -d '{"reason":"Fattura 2026/118 scaduta"}'
curl -sS -X POST "$KP/accounts/mario/unsuspend" -H "Authorization: Bearer $KEY"

# link di accesso monouso (60 secondi) che apre il file manager
curl -sS -X POST "$KP/accounts/mario/login-link" -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -d '{"next":"/files"}'

PHP

<?php
$base = 'https://server1.example.com:8443/api/v1';
$key  = getenv('KOAPANEL_API_KEY');

function kp(string $method, string $path, ?array $body = null, array $headers = []): array {
    global $base, $key;
    $ch = curl_init($base . $path);
    $h = ['Authorization: Bearer ' . $key, 'Accept: application/json'];
    foreach ($headers as $k => $v) { $h[] = "$k: $v"; }
    if ($body !== null) { $h[] = 'Content-Type: application/json'; curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body)); }
    curl_setopt_array($ch, [CURLOPT_CUSTOMREQUEST => $method, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => $h, CURLOPT_TIMEOUT => 30]);
    $raw = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);
    $data = $raw === '' ? [] : json_decode($raw, true);
    if ($code >= 400) { throw new RuntimeException($data['error']['message'] ?? "HTTP $code", $code); }
    return $data ?? [];
}

// tutti gli account, pagina per pagina
$cursor = null;
do {
    $page = kp('GET', '/accounts?limit=100' . ($cursor ? '&cursor=' . urlencode($cursor) : ''));
    foreach ($page['accounts'] as $a) { echo $a['username'], ' ', $a['usage']['diskBytes'], "\n"; }
    $cursor = $page['nextCursor'] ?? null;
} while ($cursor);

// un database per il sito del cliente
$db = kp('POST', '/databases', ['name' => 'mario_shop', 'site' => 'mario.example.com'], ['Idempotency-Key' => 'order-10452-db']);
echo $db['credentials']['user'], ' / ', $db['credentials']['password'], "\n";

Python

import os, requests

BASE = "https://server1.example.com:8443/api/v1"
S = requests.Session()
S.headers["Authorization"] = "Bearer " + os.environ["KOAPANEL_API_KEY"]

def kp(method, path, **kw):
    r = S.request(method, BASE + path, timeout=30, **kw)
    if r.status_code == 429:
        raise RuntimeError(f"rate limit, retry in {r.headers['Retry-After']} s")
    if r.status_code >= 400:
        raise RuntimeError(r.json()["error"]["message"])
    return r.json() if r.content else None

site = kp("POST", "/sites", json={"domain": "mario.example.com", "owner": "mario"},
          headers={"Idempotency-Key": "order-10452-site"})
box = kp("POST", "/mailserver/domains/mario.example.com/mailboxes", json={"local": "info", "quotaMB": 2048})
print(box["address"], box.get("password"))  # la password generata si vede una volta

Webhook

Registra l'indirizzo del tuo sistema (Chiavi API › Webhook, oppure POST /webhooks) e ricevi una richiesta POST a ogni evento:

Il corpo è {"id":"evt_…","type":"account.suspended","createdAt":"…","data":{…}} e le intestazioni X-Koapanel-Event, X-Koapanel-Delivery e X-Koapanel-Signature: t=<secondi>,v1=<firma>, dove la firma è l'HMAC-SHA256 esadecimale di "<t>.<corpo>" con il segreto del webhook (mostrato una sola volta alla creazione). Rispondi 2xx entro 10 secondi; altrimenti il pannello riprova dopo 10 s, 1 min, 5 min, 30 min e 2 h. Gli amministratori ricevono tutti gli eventi, i rivenditori solo quelli dei propri clienti (e solo verso indirizzi https:// pubblici).

Verifica in PHP:

$body = file_get_contents('php://input');
$sig  = $_SERVER['HTTP_X_KOAPANEL_SIGNATURE'] ?? '';
parse_str(str_replace(',', '&', $sig), $p);   // t=…, v1=…
$ok = isset($p['t'], $p['v1']) && abs(time() - (int)$p['t']) < 300
   && hash_equals(hash_hmac('sha256', $p['t'] . '.' . $body, getenv('KOAPANEL_WEBHOOK_SECRET')), $p['v1']);
if (!$ok) { http_response_code(400); exit; }
$event = json_decode($body, true);

Verifica in Python:

import hmac, hashlib, time

def verify(secret: str, header: str, body: bytes, tolerance=300) -> bool:
    parts = dict(x.split("=", 1) for x in header.split(","))
    if abs(time.time() - int(parts.get("t", 0))) > tolerance:
        return False
    mac = hmac.new(secret.encode(), parts["t"].encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, parts.get("v1", ""))

Moduli pronti

• WHMCS 8.x e 9.x: modulo ufficiale (account, rivenditori, accesso con un clic, licenze per i partner) — vedi la pagina «Integrazione WHMCS».
• In programma: moduli per Blesta e HostBill, e FOSSBilling. Nel frattempo questi sistemi possono usare l'API qui sopra (le operazioni sono le stesse del modulo WHMCS).

Partner API: rivendere licenze KoaPanel

Per i provider che vendono licenze KoaPanel ai propri clienti, con il modulo WHMCS koapanel_license o con qualsiasi altro sistema di fatturazione. Non è l'API del pannello: è l'API della console di KoaPanel, con una chiave partner che ti diamo noi.

export KPP=kpp_...   # la chiave partner
curl -sS -X POST https://console.koapanel.app/api/v1/partner/licenses \
  -H "Authorization: Bearer $KPP" -H "Content-Type: application/json" \
  -H "Idempotency-Key: ordine-10452" \
  -d '{"plan":"pro","externalId":"ordine-10452","customer":{"name":"Bianchi Srl","email":"it@bianchi.example","country":"IT"}}'

La risposta contiene license.id e license.token: il cliente incolla il codice in KoaPanel › Piano e licenza, e la licenza si lega a quel server. Le licenze dei partner non mostrano i piani e la pagina d'acquisto di KoaPanel.

Fatturazione all'ingrosso. Ogni licenza costa il prezzo partner mensile del suo piano (listino riservato a fasce di volume, nell'area partner), in proporzione al tempo nel mese (i cambi di piano si contano dal momento del cambio; una licenza sospesa si paga, una revocata fino alla fine del giorno della revoca). A inizio mese ricevi la fattura elettronica del mese precedente, con il dettaglio per licenza in GET /statements/{mese}. Per diventare partner richiedi l'accreditamento.

Specifica OpenAPI 3.1 della Partner API · OpenAPI del pannello sulla demo