PanelDOCSv1.0.0

Licence API

The licence server addresses under /v1/licence that paid-edition servers use to check in, start trials, report installs and download releases.

The licence server is part of the publisher's own HF Panel only, at https://api.hostfog.com/v1/licence/…. Paid-edition servers use it on their own: to check their licence, start a trial, report installs and updates, and fetch the newest release. You do not need to call it yourself.

Note: on every other server these addresses answer 404 Not found. They are described here so that you know what a licensed server sends, for example when you set up a firewall.

These addresses need no session and no API token. They answer plain JSON, not the token API's {ok, data} format. They are on the licence server's API address only.

Method Path What it does
POST /v1/licence/check a licensed server checks in: {"key","hostname","version","accounts","ips"}. The answer is signed (payload, sig)
POST /v1/licence/trial starts a trial for the calling server's IP address: {"email"}. Answers {"key","days","trial_ends"}, or 409 with the reason (for example, a trial already used)
POST /v1/licence/event an install, update or uninstall report from a paid-edition server
GET /v1/licence/pubkey the public key that signs every answer, as base64 text
GET /v1/licence/release the signed note of the newest paid-edition release: version, notes, SHA-256, size and date
GET /v1/licence/download?key=… the paid installer for a licence key, with the key written in (its HF_KEY line: bash latest needs no --licence); 403 for an unknown key. The download server's short address https://cdn.<domain>/latest/licence/KEY passes on here

Check-in

ips is optional: the server's own addresses, at most 32 are read. A licence for a public IPv4 address must check in from that address. A licence for a private, loopback, link-local, CGNAT or IPv6 address (a server behind NAT) passes when that address is one of ips.

Install reports

The paid edition's installer, updater and uninstaller send a report when the server has a licence key:

bash
curl -fsS -H 'Content-Type: application/json' https://api.hostfog.com/v1/licence/event \
     -d '{"key":"HFL-ABCDE-FGHJK-MNPQR-STUVW","event":"install_finished","version":"1.0.0","os_name":"Ubuntu","os_version":"24.04","cpus":4,"ram_mb":8192,"disk_gb":80,"domain":"yourdomain.com"}'
Field What it holds
key the licence key, required
event required: install_started, install_finished, install_failed, update_finished, update_failed or uninstalled
version, hostname, os_name, os_version about the server
cpus, ram_mb, disk_gb the server's size
step, error failures only: the step that stopped and a short error
domain, company the server's own domain and company name
Status Body
200 {"ok":true,"known":true} ("known":false for a key that is not a licence)
400 {"error":"invalid JSON"}, {"error":"invalid licence key"} or {"error":"unknown event"}
405 {"error":"POST only"}
429 {"error":"too many attempts"}

Rate limits

Each address limits how often one IP address may call it, for example 120 check-ins and 5 trial requests an hour. Over the limit, it answers 429.

Partner API

Hosting companies with bulk licences manage them from their own systems — for example issuing a licence when they create a server and removing it when they delete one. Each partner gets an API key (hfp_…) from the publisher; send it as Authorization: Bearer hfp_…. A partner sees and changes only its own licences. The Partner guide covers the bulk calls, the fleet view, webhooks and rollout in full.

Method Address Body Answer
GET /v1/licence/partner/licences — {"quantity", "used", "licences": [{"key", "email", "ip", "status", "install"}]}
POST /v1/licence/partner/issue {"key", "install"} — one licence from the pool, for that server
POST /v1/licence/partner/move {"key", "ip"} — the licence to another server
POST /v1/licence/partner/remove {"removed"} — frees its place in the pool
POST /v1/licence/partner/issue-bulk {"issued", "failed", "results"} — up to 500 at once
POST /v1/licence/partner/remove-bulk {"removed", "failed", "results"} — up to 500 at once
GET /v1/licence/partner/fleet ?page, ?per, ?status, ?version every licence with its server's last check-in, version, accounts and status, paged

install is the install command with the key in it, to run on the new server. A partner on the LTS release channel gets the LTS installer and updates from it; a partner billed by use has no pool, only an optional cap (409 when it is reached), and is billed each month for that month's peak. The addresses are on api.hostfog.com (and /licence/api/partner/… on the panel's address). Every POST takes an Idempotency-Key header for safe retries, and a partner can have a signed webhook. The full reference is Partner API and Partner webhooks.

bash
curl -s https://api.hostfog.com/v1/licence/partner/issue \
  -H "Authorization: Bearer hfp_…" \
  -d '{"email": "customer@example.com", "ip": "203.0.113.10"}'
Status Means
400 a malformed Idempotency-Key header
401 no API key, or not a valid one
403 the partner's bulk licences are not active (payment)
404 no such licence among the partner's
405 the wrong method (GET for licences and fleet, POST for the others)
409 refused, with {"error": "…"}: the pool is full, the server already has a licence, not a public IPv4 address, an atomic bulk call with a refused item
422 a malformed body or query (more than 500 bulk items), or an Idempotency-Key used for another call
429 too many calls — try again later

Checking a licence key (public)

Anyone can check that a licence key is genuine and working — the website's Verify a licence page uses this. No key or sign-in is needed; 120 checks an hour per address.

Method Path Answer
GET /v1/licence/verify?key=HFL-… {"valid", "status", "plan", "until"} — status is active, trial, ended or unknown; until the date it works until

It never shows who owns the licence, an email address, a server or an IP address.