Files

T

Grant ca32309ad9 Add StartOS instructions.md; fix manifest links; clear retired-enforce-mode drift

- instructions.md: new, required for Start9 community-registry submission
- manifest: fix dead packageRepo and docsUrls links
- versions/v0.2.0.ts: drop stale 'NOT YET WIRED' header
- actions: remove retired enforce-mode references; showLicenseStatus no longer
  reads a nonexistent 'mode' field; relabel the Creator (free) tier

2026-06-13 06:40:11 -05:00

4.1 KiB

Raw Blame History

Keysat Licensing — Instructions

Keysat is a Bitcoin-native, self-hosted licensing service for software creators. You run your own instance, hold your own signing key, and issue Ed25519-signed license keys that your software verifies offline. There is no central authority and no shared database.

Before you start

BTCPay Server is required. Install and start BTCPay Server first — Keysat uses it to take Bitcoin/Lightning payments and confirm settlement. StartOS lists this dependency before it lets you install Keysat.
A clearnet domain is recommended if you sell to the public, so buyers anywhere can reach your checkout. LAN/Tor-only works for testing.
Zaprite is optional (adds card payments). You connect it later from inside the admin web UI; nothing to do up front.

First-time setup

Get your admin API key. Open the Actions tab and run Show admin API key. Copy it — you sign into the admin web UI with it the first time.
Open the admin dashboard. Click Launch UI on the Admin Web UI interface and paste the admin API key to sign in.
(Recommended) Set a real password. Run the Set web UI password action (Actions tab, minimum 12 characters). After this the login page shows a password field; the admin API key keeps working for automation.
Connect your payment provider. In the admin web UI's Settings, use the one-click Connect BTCPay flow to authorize Keysat against your BTCPay Server. (Optionally connect Zaprite here too.)
Set your operator name in the admin web UI — it appears on buyer-facing checkout and receipts.
Create what you sell. Use Create product for each item, and optionally Create policy to set per-product defaults (duration, grace period, entitlements, seat cap, trial flag). A policy slugged default is the one the public purchase flow uses.

Activation is optional. Keysat runs out of the box at the free Creator tier (up to 5 products, 5 policies per product, and 10 active discount codes). Activating a license lifts those caps and unlocks recurring billing and Zaprite (card) payments. To activate, get a key at registry.keysat.xyz, run the Activate Keysat license action, and confirm with Show Keysat license status.

Selling licenses

Share your Licensing API URL with buyers and bake it into your software as the validation endpoint. Buyers call POST /v1/purchase, pay via BTCPay, and Keysat issues a signed license key. Your software validates keys against POST /v1/validate — including revocation checks, which return ok: false with reason: "revoked".

The same admin web UI covers manual license issuance (comps, press, trials), suspension/unsuspension, revocation, machine management, discount codes, outbound webhooks, and the audit log.

Interfaces and exposure

Licensing API (/) — public-facing. This is the URL you share with customers and bake into your builds.
Admin Web UI (/admin) — your dashboard. Restrict this interface to LAN or Tor only; the public internet does not need to reach it.
BTCPay webhook endpoint (/btcpay) — registered with BTCPay automatically during the Connect BTCPay flow. Not for human use.

Backups and uninstalling

Your data volume holds the SQLite database — which contains your server signing key and every license record — and StartOS backs it up automatically. Your self-license at /data/keysat-license.txt is included in the backup and survives upgrades and reinstalls.

Uninstalling deletes your signing key and all license records. Once it is gone, previously issued license keys no longer validate against this server. Back up first if you plan to reinstall.

Recovery

Locked out of the admin UI? Run Set web UI password to set a new one, or Show admin API key to sign in with the key.
Lost your Keysat license? Re-run Activate Keysat license with your key.

Full developer and integration documentation lives in the upstream repository (README.md and KEYSAT_INTEGRATION.md) and at keysat.xyz.

4.1 KiB Raw Blame History