billingHelp

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#

  1. Create a leased product
  2. Embed the key in the binary
  3. Publish a download
  4. How customers get a license
  5. What billing decides on every check
  6. Reading the instance list
  7. Managing a license
  8. Rotating a signing key — and a compromised key
  9. Admin JSON API
  10. Endpoints, limits and URL modes
  11. Jobs, self-check, storage
  12. Troubleshooting

1. Create a leased product#

Products → product → Licensing (owners and admins).

FieldMeaning
ModeNone (an ordinary product) or Lease (a licensed binary).
Product codeCompiled into the binary, e.g. cacheproxy. 2–32 characters a-z 0-9 _ -, unique in the workspace.
Seats per licenseHow 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.
FeaturesOptional 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 / VersionThe 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's upload_max_filesize / post_max_size and Nginx's client_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 example 3/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.

EventResult
Start free trialA 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 purchaseA 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 revokeThe 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.

ReasonWhen
unknown_keyNo license has that key (wrong key, or replaced by Issue a new key).
product_mismatchThe key belongs to another product code.
product_disabledThe product is not in lease mode, not active, or deleted.
disabledThe workspace or the customer is disabled, or the license is suspended. When suspended, your message is shown.
revokedThe license was revoked.
expiredThe 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.
unpaidThe subscription is past due beyond the grace period, or unpaid.
seat_limitA new machine while every seat is in use. Machines already counted are never refused for seats.
instance_blockedThat 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:

ActionEffect
Suspend (message)Denied disabled with your message.
ResumeServed again at the next check.
RevokeDenied revoked.
SeatsA reduction applies as copies go stale or are removed.
End dateA hard end date; empty means none.
Issue a new keyEvery 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> or super:<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:

  1. Create pending key (k2). Its public key appears in the table and in the embed block.
  2. Rebuild the product with both k1 and k2 in license_keys.go, and roll the build out.
  3. Activate k2. In one step, k1 is retired and its secret is erased; its public key stays for the record. Old builds that know only k1 stop verifying from this moment, which is why step 2 comes first.
  4. Drop k1 from 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#

ItemDetail
AuthenticationSame 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.
ResponsesJSON. Errors are RFC 7807 problem documents.
KeysThe license key is never returned; reveal it in the dashboard.
URL formClean 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.

EndpointClean URLs (front controller)Plain PHP vhost
LeasePOST /api/v1/license/leasePOST /api/?r=v1/license/lease
Release (on shutdown)POST /api/v1/license/releasePOST /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: ok with a signed lease, or denied with a reason.
  • 400 for a malformed request.
  • 405 for anything but POST.
  • 429 when rate-limited, with retry_s in the body and a Retry-After header.
  • 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 whose trial_end passed.
  • 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 on products.
  • 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#

SymptomLook 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 503Self-check, "Leased products can sign leases".
Copies keep running after a cancelThey 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 emailSuper → Email, the outbox. One email per license per 24 h.