API Documentation
Complete technical reference and integration guide for connecting WHBOS installations, client server probes, SDK clients, and custom billing automation with the WHBOS Cryptographic Licensing Authority.
Returns real-time authority status, cryptographic engine readiness, and server ISO-8601 timestamp. Authenticated administrators receive additional operational licensing telemetry.
{
"status": "operational",
"service": "WHBOS License Authority API",
"version": "v2.0",
"authority": "Ed25519 Cryptographic Canonical Authority",
"timestamp": "2026-09-06T20:50:00+00:00"
}
The unsigned validation endpoint is strictly read-only. It checks key validity, detects edition entitlements (Unbranded / White-Label vs Branded OS), and returns support/update validity. It never mutates server bindings, allocates seats, or issues cryptographic leases. Safe for pre-flight installation checks and remote audits.
| Field | Type | Required | Description |
|---|---|---|---|
| license_key | string | Yes | Official license key string (e.g. WHBOS-H9TC-F6QP-TYCA-UBUX). |
| domain | string | Optional | Target installation hostname (e.g. portal.bluerack.net). |
| server_ip | string | Optional | Server public IPv4 address. |
| device_public_key | string | Optional | Base64 encoded device public key to query existing activation ID if enrolled. |
{
"success": true,
"status": "active",
"activation_id": null,
"plan": "Unbranded Lifetime",
"billing_cycle": "owned",
"is_lifetime": true,
"is_branded": false,
"white_label": true,
"domain": "portal.bluerack.net",
"ip_address": "103.120.176.45",
"client_name": "Kuldeep Singh",
"expires_at": null,
"support_expires_at": "2027-09-06T20:50:00+00:00",
"has_active_support": true,
"can_receive_updates": true,
"lease": null,
"message": "License validated successfully (read-only verification)."
}
Enrolls an installation node bound to a unique Ed25519 device public key, allocates an authorized seat against the license's seat limit (max_activations), and issues a cryptographically signed 30-day offline entitlement lease token.
{
"license_key": "WHBOS-H9TC-F6QP-TYCA-UBUX",
"device_public_key": "bA+6vYhmQaJBtQ5rIdPsTZVLgia+QX3gf1c/2MC6/O4=",
"device_sig": "X8v0pL9q8b1c...detached_signature_bytes...",
"timestamp": 1788371000,
"nonce": "7f8b92c10a3d4e5f",
"counter": 1,
"domain": "portal.bluerack.net",
"fingerprint": {
"domain": "portal.bluerack.net",
"server": "Linux 6.8.0-x86_64",
"hardware": "a8f9c10d3e2b"
}
}
{
"success": true,
"status": "activated",
"activation_id": 42,
"lease": "whbos_v2_lease.eyJ2IjoyLCJ0eXAiOiJsZWFzZSIsImFpZCI6NDIsImxpYyI6IldIQk9TLUg5VEM...sig",
"lease_expires_at": "2026-10-06T20:50:00+00:00",
"grace_until": "2026-10-13T20:50:00+00:00",
"plan": "Unbranded",
"is_branded": false,
"white_label": true
}
Runs periodically via server cron (typically every 24 hours) to re-verify active seat validity and renew the 30-day offline cryptographic lease. Strictly enforces monotonic counter checking and device public key verification to block replay attacks.
{
"license_key": "WHBOS-H9TC-F6QP-TYCA-UBUX",
"activation_id": 42,
"device_public_key": "bA+6vYhmQaJBtQ5rIdPsTZVLgia+QX3gf1c/2MC6/O4=",
"device_sig": "A9x3kL...signature_bytes...",
"timestamp": 1788457400,
"nonce": "8a1b2c3d4e5f6071",
"counter": 2,
"domain": "portal.bluerack.net"
}
{
"success": true,
"status": "heartbeat_ok",
"activation_id": 42,
"plan": "Unbranded",
"domain": "portal.bluerack.net",
"ip_address": "103.120.176.45",
"heartbeat_interval_hours": 24,
"next_heartbeat_at": "2026-09-07T20:50:00+00:00",
"lease": "whbos_v2_lease.eyJ2IjoyLCJ0eXAiOiJsZWFzZSIsImFpZCI6NDIsImxpYyI6IldIQk9TLUg5VEM...sig",
"lease_expires_at": "2026-10-07T20:50:00+00:00",
"grace_until": "2026-10-14T20:50:00+00:00"
}
Releases an active device seat from the license, marks the activation record as deactivated, and issues a cryptographically signed revocation notice. This immediately frees the seat slot for assignment to another host node.
{
"license_key": "WHBOS-H9TC-F6QP-TYCA-UBUX",
"activation_id": 42,
"device_public_key": "bA+6vYhmQaJBtQ5rIdPsTZVLgia+QX3gf1c/2MC6/O4=",
"device_sig": "D3f1a9...signature_bytes...",
"timestamp": 1788458000,
"nonce": "9b2c3d4e5f607182"
}
{
"success": true,
"status": "deactivated",
"notice": {
"type": "revocation",
"license_key": "WHBOS-H9TC-F6QP-TYCA-UBUX",
"activation_id": 42,
"reason": "Deactivated by client device request",
"revoked_at": "2026-09-06T20:50:00+00:00"
}
}
Performs an atomic server migration: deactivates this device's existing seat (if any) and re-activates with fresh host binding in a single database transaction. Prevents seat lockouts, double-accounting, or nonce-replay failures during hardware or hostname migrations.
{
"license_key": "WHBOS-H9TC-F6QP-TYCA-UBUX",
"activation_id": 42,
"device_public_key": "bA+6vYhmQaJBtQ5rIdPsTZVLgia+QX3gf1c/2MC6/O4=",
"device_sig": "E4a2b8...signature_bytes...",
"timestamp": 1788460000,
"nonce": "1a2b3c4d5e6f7081",
"counter": 3,
"domain": "newportal.bluerack.net"
}
{
"success": true,
"status": "transferred",
"activation_id": 43,
"lease": "whbos_v2_lease.eyJ2IjoyLCJ0eXAiOiJsZWFzZSIsImFpZCI6NDMsImxpYyI6IldIQk9TLUg5VEM...sig",
"lease_expires_at": "2026-10-06T20:50:00+00:00",
"grace_until": "2026-10-13T20:50:00+00:00"
}
Queries the release hub for newer WHBOS Core packages matching the specified channel (stable, beta, rc). Returns release changelogs, PHP version requirements, and signed upgrade manifests.
{
"update_available": true,
"current_installed": "1.0.0",
"latest_version": "2.4.0",
"channel": "stable",
"php_requirement": "8.3+",
"release_date": "2026-09-01",
"changelog": "Enterprise security enhancements, high-throughput queue workers, and multi-currency billing fixes.",
"download_url": "https://whbos.com/api/v2/release/download?version=2.4.0",
"manifest": "whbos_v2_manifest.eyJ2ZXIiOiIyLjQuMCIsImNoYW5uZWwiOiJzdGFibGUi...sig",
"sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}
Returns the cryptographic SHA-256 integrity hash and signed release manifest token for a specific software release package. Used by the auto-updater to verify binary authenticity prior to extraction.
?version=2.4.0 (Required — Specific release tag)
{
"version": "2.4.0",
"sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"manifest": "whbos_v2_manifest.eyJ2ZXIiOiIyLjQuMCIsImNoYW5uZWwiOiJzdGFibGUiLCJzaGEyNTYiOiJlM2IwYzQ0Mjk4Zm...sig"
}
Streams the official production ZIP archive for authorized core upgrades or redirects to validated CDN mirrors with SSRF defense verification.
?version=2.4.0 (Required)
Ed25519 Canonical Request Signing Specification
All mutating API v2 endpoints (activate, heartbeat, deactivate, transfer) require detached Ed25519 signatures.
Canonical String Representation Format:
The message signed by the device private key is constructed by joining exactly 10 fields with newline (\n) characters:
v2.lic-req
{HTTP_METHOD}
{REQUEST_PATH}
{timestamp}
{nonce}
{counter}
{license_key}
{activation_id}
{device_public_key}
{fingerprint_hash}
• Scheme Prefix: Always literal string v2.lic-req.
• HTTP_METHOD: Uppercase HTTP verb (e.g. POST).
• REQUEST_PATH: Path without trailing slash (e.g. /api/v2/license/activate).
• fingerprint_hash: SHA-256 hash of domain + "\x1f" + server + "\x1f" + hardware.
• Anti-Replay Nonce: Cryptographically random string cached atomically on the server for 900 seconds.
<?php
// Generate 10-line canonical message
$canonical = implode("\n", [
'v2.lic-req',
'POST',
'/api/v2/license/activate',
$timestamp,
$nonce,
(string) $counter,
$licenseKey,
$activationId ?? '',
$devicePublicKeyB64,
hash('sha256', implode("\x1f", [$domain, $serverInfo, $hardwareId])),
]);
// Sign using Ed25519 private key
$signatureBytes = sodium_crypto_sign_detached($canonical, $deviceSecretKey);
$deviceSigB64 = base64_encode($signatureBytes);
cURL Quick Start Example
Probe and test license status directly from your shell or provisioning scripts:
# Read-only license verification probe
curl -X POST "https://whbos.com/api/v2/license/validate" \
-H "Content-Type: application/json" \
-d '{
"license_key": "WHBOS-H9TC-F6QP-TYCA-UBUX",
"domain": "portal.bluerack.net",
"server_ip": "103.120.176.45"
}'
Official PHP Client SDK Integration
Use the zero-dependency WhbosLicenseClient.php to enforce licensing in custom PHP apps, modules, and plugins.
<?php
require_once __DIR__ . '/sdk/WhbosLicenseClient.php';
$client = new \WHBOS\SDK\WhbosLicenseClient(
serverUrl: 'https://whbos.com',
licenseKey: 'WHBOS-H9TC-F6QP-TYCA-UBUX',
storagePath: __DIR__ . '/storage/license_lease.json'
);
// 1. Initial server node activation (allocates seat + downloads signed lease)
$activation = $client->activate($_SERVER['HTTP_HOST'] ?? 'localhost');
// 2. Continuous license verification (verifies local cryptographic lease with offline fallback)
$check = $client->verify();
if ($check['valid']) {
echo "License Active! Plan: " . $check['plan'] . "\n";
echo "White Label Enabled: " . ($check['white_label'] ? 'Yes' : 'No');
} else {
die("Access Denied: " . $check['reason']);
}