Grant
ca32309ad9
- 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
88 lines
4.1 KiB
Markdown
88 lines
4.1 KiB
Markdown
# 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
|
|
|
|
1. **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.
|
|
2. **Open the admin dashboard.** Click **Launch UI** on the **Admin Web UI**
|
|
interface and paste the admin API key to sign in.
|
|
3. **(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.
|
|
4. **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.)
|
|
5. **Set your operator name** in the admin web UI — it appears on buyer-facing
|
|
checkout and receipts.
|
|
6. **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](https://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.
|
|
|
|
## More
|
|
|
|
Full developer and integration documentation lives in the upstream repository
|
|
(`README.md` and `KEYSAT_INTEGRATION.md`) and at
|
|
[keysat.xyz](https://keysat.xyz).
|