Licensing (software products)
Selling licensed binaries — leased products, signing keys, downloads, seats, trials, and managing licenses and machines.
Software sold through the platform runs with a license key. The program asks the platform for a signed lease every few minutes and keeps serving only while it holds a valid one. When you disable the customer or the product, or payment stops, the program stops within one check interval; it resumes by itself when the problem is fixed.
Licensed Go binaries sold through billing. A customer gets a license key, downloads the binary and runs it with the key. The binary asks billing for a signed lease every few minutes. It keeps serving only while it holds a valid lease.
If you disable the customer or the product, or payment stops, the binary stops within one check interval. It resumes by itself once the problem is fixed: no restart, no new key.
The full specification is LICENSING-BILLING-v0.1.0.md (Part A). How it maps onto billing's tables is described in amendment v0.3.0 §H14. The Go side is the golicense package (LICENSING-GO-v0.1.0, a separate project).
Contents#
- Create a leased product
- Embed the key in the binary
- Publish a download
- How customers get a license
- What billing decides on every check
- Reading the instance list
- Managing a license
- Rotating a signing key — and a compromised key
- Admin JSON API
- Endpoints, limits and URL modes
- Jobs, self-check, storage
- Troubleshooting
1. Create a leased product#
Products → product → Licensing (owners and admins).
| Field | Meaning |
|---|---|
| Mode | None (an ordinary product) or Lease (a licensed binary). |
| Product code | Compiled into the binary, e.g. cacheproxy. 2–32 characters a-z 0-9 _ -, unique in the workspace. |
| Seats per license | How many machines may run one license at the same time (new licenses start with this value). |
| Lease TTL (s) | How long a copy keeps running with no contact. This is the offline grace period. Default 86400 (24 h); allowed 3600–604800. |
| Check every (s) | How often a copy checks in, so how fast a pause or a fix reaches it. Default 300; allowed 60–3600; must be below the TTL. |
| Past-due grace (days) | After a renewal fails, how long leases are still granted (with a warning) before service pauses. Default 3. |
| Features | Optional JSON object sent in every lease, e.g. {"max_tenants": 10, "http3": true}. A license can override single keys (API/DB field features_override). |
| Download file / Version | The build customers download (section 3). The version is sent to running copies as latest_version. |
Saving in Lease mode does three things:
- Creates signing key
k1(active). - Backfills licenses for customers who already have paid or complimentary access to the product.
- Shows the lease endpoint (with the URL form your server uses) and the trial status.
Offering a free trial. Add a recurring plan (monthly, quarterly or annual) with trial days. The pay page then shows Start free trial (no card) to signed-in customers.
2. Embed the key in the binary#
The Licensing panel shows a ready block for license_keys.go:
// license_keys.go — generated from the billing admin "Licensing" panel. Keep ≥ 1 key.
package main
const productCode = "cacheproxy"
var licensePublicKeys = map[string]string{
"k1": "3f1c…64 hex characters…",
}
Copy it into the product's repository. It holds only public keys; the secret halves never leave billing. They are sealed with the install's master key (data/keys/master.key).
3. Publish a download#
Choose one of two ways:
- Upload a build on the Licensing panel. It is stored in
data/downloads/<workspace id>/<code>/<file name>. Uploads are limited by PHP'supload_max_filesize/post_max_sizeand Nginx'sclient_max_body_size. - Copy the file to the server and enter its name in Download file. Use this for large binaries. The name is relative to
data/downloads/, for example3/cacheproxy/cacheproxy-1.4.2-linux-amd64. Path traversal is refused, and the file must exist.
Customers download from /account/<workspace>/download/<code>. They must be signed in and hold a license for the product that is not revoked. The file is streamed from outside the webroot as an attachment, 1 MB at a time.
4. How customers get a license#
One license exists per customer × product. Its key does not change when a trial becomes paid.
| Event | Result |
|---|---|
| Start free trial | A subscription with provider none (no card, no provider calls), status trialing, until trial_end. Paid access is granted for the trial, and a license is created. The license page opens with the key, the download and the run command. One trial per customer and product: a second attempt goes to checkout ("Trial already used"). The provider checkout of a customer who already had the no-card trial gets no second trial. |
| Subscribe (any provider) | The license is attached to the new subscription; the key is kept. The no-card trial is closed. |
| One-time purchase | A license without a subscription. It works while the purchase gives access: a full refund or chargeback ends it. |
| Offline payment (customer page) | Same as a one-time purchase; an end date set there caps the license. |
| Complimentary access (customer page) | A license, capped at the comp end date. Comp also keeps a license running when its subscription has ended. |
| A new purchase after a revoke | The license comes back with a new key. A renewal of the same subscription never undoes a revoke. |
When the trial ends. Leases are denied as soon as trial_end passes. Within 15 minutes the job licensing.trials closes the trial subscription, and access falls back (to Free if the product has a Free plan). Customers can also end a trial at once from their account page.
5. What billing decides on every check#
The checks run in this order; the first one that fails decides the reason.
| Reason | When |
|---|---|
unknown_key | No license has that key (wrong key, or replaced by Issue a new key). |
product_mismatch | The key belongs to another product code. |
product_disabled | The product is not in lease mode, not active, or deleted. |
disabled | The workspace or the customer is disabled, or the license is suspended. When suspended, your message is shown. |
revoked | The license was revoked. |
expired | The trial is over; the subscription was canceled (immediately, or after the paid period); it is paused or incomplete; or the license's own end date passed. |
unpaid | The subscription is past due beyond the grace period, or unpaid. |
seat_limit | A new machine while every seat is in use. Machines already counted are never refused for seats. |
instance_blocked | That machine was blocked. |
Grants. A grant is a signed lease with state: active, trialing (capped at the trial end) or past_due (capped at the grace end, with a warning message).
Messages. Denials carry a human message and a link to the customer's license page. The binary shows both on screen.
The paused-service email. The first unpaid or expired denial emails the customer (template license_paused), at most once per license per 24 hours.
6. Reading the instance list#
Each running copy is one instance: one machine, identified by a hash of its machine id. Columns:
- Host, plus the id and version.
- Last check, plus when it was first seen.
- IP and OS / client.
- Status:
- active: checking in and served;
- denied: checking in and refused; the reason is shown;
- released: shut down cleanly; its seat is free;
- stale: silent for more than 2 × the lease TTL; its seat is free;
- blocked.
Possible clone (same machine-id, different hostnames). The same machine id reported different host names within two check intervals, typically a cloned VM. It occupies one seat; machine-id binding cannot tell clones apart. Clones are flagged, not silently allowed. Block the instance, or ask the customer to reset the clone's /etc/machine-id.
Actions (customers can do these on their own licenses too):
- Remove frees the seat now. A removed copy that is still running takes a seat again at its next check.
- Block / Unblock stops or allows that machine.
7. Managing a license#
Licenses (menu) lists every license. Filter by product and status, or search by email, full key or the last 4 characters. A customer's page also has a Licenses section.
On the license page, owners and admins can:
| Action | Effect |
|---|---|
| Suspend (message) | Denied disabled with your message. |
| Resume | Served again at the next check. |
| Revoke | Denied revoked. |
| Seats | A reduction applies as copies go stale or are removed. |
| End date | A hard end date; empty means none. |
| Issue a new key | Every running copy is denied unknown_key until it is restarted with the new key. |
Permissions. Finance viewers can see licenses but not change them. Admins with product access limited to some products see only those products' licenses.
Super admins. Platform → Licenses lists the licenses of every workspace and can act on them. Their actions are logged as super:<id>.
Every action is recorded twice:
- in the license history, as
admin:<id>,customer:<id>orsuper:<id>; - in the audit log.
8. Rotating a signing key — and a compromised key#
Only the active key signs. Each leased product has exactly one active key. To rotate without a glitch:
- Create pending key (
k2). Its public key appears in the table and in the embed block. - Rebuild the product with both
k1andk2inlicense_keys.go, and roll the build out. - Activate
k2. In one step,k1is retired and its secret is erased; its public key stays for the record. Old builds that know onlyk1stop verifying from this moment, which is why step 2 comes first. - Drop
k1from the next build.
A compromised key. Do steps 1–3 as fast as the rollout allows. A forged grant can live at most one lease TTL. If the secret leaked together with the master key, also rotate the master key. That is out of scope here; see INSTALL.
9. Admin JSON API#
| Item | Detail |
|---|---|
| Authentication | Same session as the admin screens. Every POST and DELETE needs X-CSRF-Token, set to the value of the bcsrf cookie (__Host-bcsrf over HTTPS). Run 6 adds API keys. |
| Responses | JSON. Errors are RFC 7807 problem documents. |
| Keys | The license key is never returned; reveal it in the dashboard. |
| URL form | Clean URLs are shown. Plain vhosts use /admin/index.php?r=api/licenses…. |
GET /admin/api/licenses?customer_id=<pub>|product_id=<pub>|status=active|suspended|revoked|q=…
GET /admin/api/licenses/{id} license + instances + last 50 events
POST /admin/api/licenses/{id}/suspend {"reason":"…"}
POST /admin/api/licenses/{id}/resume
POST /admin/api/licenses/{id}/revoke
POST /admin/api/licenses/{id}/seats {"seats":5}
POST /admin/api/licenses/{id}/regenerate
POST /admin/api/licenses/{id}/expires {"expires_at":"2027-01-01T00:00:00Z"} or {"expires_at":null}
DELETE /admin/api/licenses/{id}/instances/{instance_id}
POST /admin/api/licenses/{id}/instances/{instance_id}/remove same as DELETE, for clients that cannot send DELETE
POST /admin/api/licenses/{id}/instances/{instance_id}/block or …/unblock
GET /admin/api/products/{id}/signing-keys keys + the license_keys.go block
POST /admin/api/products/{id}/signing-keys create a pending key
POST /admin/api/products/{id}/signing-keys/{kid}/activate or …/retire
{id} is the license's public id, as in its page URL. Super admins have the same license calls under /super/api/licenses…, across every workspace.
10. Endpoints, limits and URL modes#
The binary talks to two public endpoints. The license key is the credential: no session, no cookies, no CSRF.
| Endpoint | Clean URLs (front controller) | Plain PHP vhost |
|---|---|---|
| Lease | POST /api/v1/license/lease | POST /api/?r=v1/license/lease |
| Release (on shutdown) | POST /api/v1/license/release | POST /api/?r=v1/license/release |
The Licensing panel shows the exact lease URL of your server. Configure the binary's server URL to match. The production encrypted.com vhost uses clean URLs (nginx-hardened.conf).
Status codes:
- 200, always, for a well-formed request:
okwith a signed lease, ordeniedwith a reason. - 400 for a malformed request.
- 405 for anything but POST.
- 429 when rate-limited, with
retry_sin the body and aRetry-Afterheader. - 503 if the product has no usable signing key; the self-check reports this.
The client treats anything but a parseable 200 as "unreachable" and keeps running on its current lease.
Rate limits:
- Per IP: 120 lease/release calls per minute.
- Per key:
max(30, 2 × seats)per minute.
A whole fleet restarting at once is never throttled by its own size.
Behind a proxy or webgate. If a proxy or webgate sits in front of billing, make sure PHP sees the client address, or every binary shares the proxy's per-IP budget.
11. Jobs, self-check, storage#
Jobs:
licensing.trials(every 15 min) closes no-card trials whosetrial_endpassed.licensing.maintenance(daily 03:53 UTC) deletes instances unseen for 90 days and license events older than 365 days.
Self-check:
- "Leased products can sign leases" fails if an active leased product has no active key.
- "Leased products have a download" warns if an active leased product has no file.
Storage:
- Tables:
licenses,license_instances,license_events,product_signing_keys, plus licensing columns onproducts. - Keys are stored as a SHA-256 hash for lookup, plus a sealed copy for the dashboard Reveal.
- IP addresses are stored in binary form.
- Downloads live in
data/downloads/.
Interop check (per release). app/tests/fixtures/envelope.json is an envelope signed over real Nginx, and envelope.pub is its public key. Verify them with Go's standard library:
go run app/tests/interop/verify_envelope.go app/tests/fixtures/envelope.json app/tests/fixtures/envelope.pub
The golicense repository's lictest -verify-file command does the same.
12. Troubleshooting#
| Symptom | Look at |
|---|---|
| A copy says "license key not recognised" | The key was replaced (Issue a new key) or mistyped. Copy it again from the license page. |
| "All N seats in use" | The instance list: remove old machines, or raise the seats. |
| Everything answers 503 | Self-check, "Leased products can sign leases". |
| Copies keep running after a cancel | They run until their lease ends at most (TTL, 24 h by default). Shorten the TTL if that is too long. Checks see the change within one check interval. |
| The customer did not get the paused email | Super → Email, the outbox. One email per license per 24 h. |