Keysat
f99d4a4998
Add a Merchant profiles concept section to index.html: the default profile, per-profile branding and payment accounts, product routing, and the Pro/Patron multi-business capability. Wire it into the Concepts nav across all pages and the index TOC. Conforms to the brand contract (design-checker: compliant).
227 lines
17 KiB
HTML
227 lines
17 KiB
HTML
<!doctype html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<title>Keysat Docs: Introduction</title>
|
|
<link rel="icon" type="image/svg+xml" href="assets/favicon.svg">
|
|
<link rel="stylesheet" href="docs.css">
|
|
</head>
|
|
<body>
|
|
|
|
<div class="topnav">
|
|
<a href="https://keysat.xyz" class="brand" title="Back to keysat.xyz"><img src="assets/keysat-mark.svg" alt=""><span>Keysat</span></a>
|
|
<span class="docs-tag">Docs</span>
|
|
</div>
|
|
|
|
<div class="layout">
|
|
<aside class="side">
|
|
<div class="group">
|
|
<div class="glabel">Get started</div>
|
|
<a href="index.html" class="active">Introduction</a>
|
|
<a href="install.html">Install & setup</a>
|
|
<a href="integrate.html">Integrate the SDK</a>
|
|
<a href="agent.html">Agent integration</a>
|
|
</div>
|
|
<div class="group">
|
|
<div class="glabel">Concepts</div>
|
|
<a href="index.html#architecture">Architecture</a>
|
|
<a href="index.html#products-policies">Products & policies</a>
|
|
<a href="index.html#merchant-profiles">Merchant profiles</a>
|
|
<a href="index.html#discounts">Discount codes</a>
|
|
<a href="index.html#revocation">Revocation strategy</a>
|
|
</div>
|
|
<div class="group">
|
|
<div class="glabel">Reference</div>
|
|
<a href="wire-format.html">Wire format</a>
|
|
</div>
|
|
<div class="group">
|
|
<div class="glabel">Project</div>
|
|
<a href="pricing.html">Pricing</a>
|
|
<a href="license.html">License</a>
|
|
</div>
|
|
<div class="group">
|
|
<div class="glabel">Operate</div>
|
|
<a href="operate.html#backups">Backups</a>
|
|
<a href="operate.html#migrate">Migrate hardware</a>
|
|
<a href="operate.html#troubleshooting">Troubleshooting</a>
|
|
</div>
|
|
</aside>
|
|
|
|
<main class="prose">
|
|
<div class="crumb">Get started · Introduction</div>
|
|
<h1>Welcome to Keysat.</h1>
|
|
<p class="lead">Keysat lets independent software creators sell their work on their own terms. You ship software (open source, closed source, free / paid versions, whatever fits), and Keysat handles the buy page, payment via BTCPay, and a signed license for each buyer.</p>
|
|
<p>How you use that license inside your software is up to you: a one-time purchase to unlock the whole app, a free + paid split with specific paid features, a tip-jar style supporter badge: all legitimate. The licensing layer is a primitive, not a script.</p>
|
|
|
|
<p>These docs cover both ends:</p>
|
|
|
|
<div class="next-grid">
|
|
<a class="next-card" href="install.html">
|
|
<span class="eyebrow">Operator</span>
|
|
<h4>Install & setup →</h4>
|
|
<p>Sideload the package, connect BTCPay, define your first product. About an afternoon, end to end.</p>
|
|
</a>
|
|
<a class="next-card" href="integrate.html">
|
|
<span class="eyebrow">Developer</span>
|
|
<h4>Integrate the SDK →</h4>
|
|
<p>Add the SDK to your app, embed your public key, verify a license at startup. About five lines of code.</p>
|
|
</a>
|
|
<a class="next-card" href="agent.html">
|
|
<span class="eyebrow">Agent / automation</span>
|
|
<h4>Agent integration →</h4>
|
|
<p>OpenAPI spec, scoped API keys, webhooks. Build bots that issue comp licenses, react to events, or automate support flows.</p>
|
|
</a>
|
|
</div>
|
|
|
|
<h2 id="architecture">Architecture</h2>
|
|
<p>Keysat is the licensing layer sitting on top of your existing payments stack. Three boxes:</p>
|
|
<ul>
|
|
<li><strong>BTCPay Server</strong>: takes the payment. On-chain Bitcoin or Lightning, settling to your wallet. Lives on your Start9.</li>
|
|
<li><strong>Keysat</strong>: your private licensing service. Holds the Ed25519 signing key. Hosts the public purchase URLs at <code>/buy/<product></code>. Listens for BTCPay payment webhooks and issues a signed license on each settlement. Lives on your Start9.</li>
|
|
<li><strong>Your software</strong>: the thing you sell. Ships with the Keysat <em>public</em> key embedded at compile time. On startup it reads the user’s license and verifies the signature offline. No network call.</li>
|
|
</ul>
|
|
|
|
<p>The key word is <em>offline</em>. Once a license is issued, your software does not need to phone home to verify it. The verification is a pure function of the license bytes and the public key. This is the same model used by signed JWTs, except wrapped in a small fixed-width format that’s comfortable to print on a receipt.</p>
|
|
|
|
<div class="callout">
|
|
<i data-lucide="info"></i>
|
|
<p><strong>Why offline matters.</strong> Online license servers are a single point of failure for every customer who ever bought your software. With Keysat, if your Start9 disappears tomorrow, every previously-issued license still verifies. That’s sovereignty.</p>
|
|
</div>
|
|
|
|
<h2 id="products-policies">Products & policies</h2>
|
|
<p>You declare two things in Keysat: products and policies.</p>
|
|
<p>A <strong>product</strong> is the thing you sell: "Bitcoin Ticker Pro", "Aurora Plugin", whatever. It has a slug, a display name, a description, and a price (sats / USD / EUR). Each product also carries an <strong>entitlements catalog</strong>: the typed list of feature slugs your software cares about, plus their display names and descriptions. Policies pick entitlements from this catalog.</p>
|
|
<p>A <strong>policy</strong> is a license template attached to a product. It specifies:</p>
|
|
|
|
<table class="t">
|
|
<thead><tr><th>Field</th><th>Meaning</th></tr></thead>
|
|
<tbody>
|
|
<tr><td><code>duration_seconds</code></td><td>How long the license is valid. <code>0</code> means perpetual.</td></tr>
|
|
<tr><td><code>grace_seconds</code></td><td>Extra time after expiry before the verifier rejects.</td></tr>
|
|
<tr><td><code>max_machines</code></td><td>Seat cap. <code>0</code> means unlimited.</td></tr>
|
|
<tr><td><code>is_trial</code></td><td>Sets a <code>TRIAL</code> bit so your app can show a "trial" banner.</td></tr>
|
|
<tr><td><code>is_recurring</code> + <code>renewal_period_days</code></td><td>Auto-renew on a cycle (weekly / monthly / annual / custom). The daemon mints a fresh invoice + signed license per cycle.</td></tr>
|
|
<tr><td><code>entitlements</code></td><td>Subset of the product’s catalog this policy grants. Baked into the signed license.</td></tr>
|
|
<tr><td><code>metadata.marketing_bullets</code></td><td>Operator-authored ✓ items rendered on the buy-page tier card. Pure marketing copy. Not enforced.</td></tr>
|
|
<tr><td><code>metadata.hidden_entitlements</code></td><td>Slugs the license still grants but the buy-page card hides; useful when a higher tier uses "Everything in X, plus:" copy and doesn’t want to repeat implied entitlements.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<p>A product can have <strong>one policy or many</strong>. Multi-tier ladders (think Basic / Pro / Max) are first-class: when a product has two or more public policies, the buy page renders a tier picker and the buyer chooses before paying. The displayed tier is selected from a <code>?policy=<slug></code> URL hint, then the <code>highlighted</code> ("most popular") policy if any, then the cheapest. Tier ordering on the picker is operator-controlled via drag-and-drop in the admin UI (or <code>tier_rank</code> in the API).</p>
|
|
<p>You can also attach <strong>private policies</strong> for manual issuance, e.g. a longer-duration "Lifetime" comp for conferences, a richer-entitlement "Internal" tier for support cases. Private policies don’t appear on the buy page; the admin API issues them directly.</p>
|
|
|
|
<h2 id="merchant-profiles">Merchant profiles</h2>
|
|
<p>By default a Keysat instance sells for one business. On first boot it creates a single <strong>default merchant profile</strong> from your operator name, and every product you create attaches to it. If you only ever run one business, you can ignore profiles entirely: everything works against the default.</p>
|
|
<p>On the <strong>Pro</strong> and <strong>Patron</strong> tiers you can run more than one business from the same instance. A <strong>merchant profile</strong> is one business identity, and it owns:</p>
|
|
<ul>
|
|
<li><strong>Branding</strong>: display name, brand color, and the support URL / email shown on that business’s buy pages.</li>
|
|
<li><strong>Payment accounts</strong>: its own BTCPay and Zaprite connections (one, the other, or both). Payments for that business settle to that business’s wallet, never a shared one.</li>
|
|
<li><strong>A post-purchase redirect</strong>: where buyers land after paying (with <code>{invoice_id}</code> substituted), or the Keysat receipt page if you leave it blank.</li>
|
|
<li><strong>Products</strong>: each product attaches to exactly one profile. Buyers see that profile’s brand on the buy page, and their payment routes to that profile’s providers.</li>
|
|
</ul>
|
|
<p>So one operator, on one Start9, can sell Recaps under the Recaps brand (settling to the Recaps wallet) and Aurora under the Aurora brand (settling to the Aurora wallet) side by side, with separate checkout branding and separate books. Keysat is still not a shared SaaS: two independent sellers each run their own box. What profiles add is multiple businesses under one operator.</p>
|
|
|
|
<table class="t">
|
|
<thead><tr><th>Concept</th><th>What it is</th></tr></thead>
|
|
<tbody>
|
|
<tr><td>Default profile</td><td>Auto-created on first boot, exactly one per instance. A product with no explicit profile resolves to it.</td></tr>
|
|
<tr><td>Payment provider</td><td>One configured BTCPay or Zaprite account, attached to a profile. A profile can have more than one.</td></tr>
|
|
<tr><td>Rail</td><td>A buyer-facing payment method: Lightning, on-chain, or card. BTCPay serves Lightning and on-chain; Zaprite adds card.</td></tr>
|
|
<tr><td>Rail preference</td><td>A tie-breaker for when a profile has two providers that both serve the same rail: it sets which one wins.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<p>Manage all of this in the admin UI under <strong>Merchant profiles</strong>: create a profile, set its branding, connect BTCPay or Zaprite to it, mark one as the default, and attach products. Connecting a provider to a profile uses the same one-click authorize handshake as <a href="install.html#connect-btcpay">Connect BTCPay</a> in setup, just scoped to the profile you start it from.</p>
|
|
|
|
<div class="callout">
|
|
<i data-lucide="store"></i>
|
|
<p><strong>Running one business? Skip this.</strong> The default profile is created for you and every product uses it automatically. Merchant profiles only start to matter when you want a second brand or a second wallet on the same instance, which is a Pro and Patron capability.</p>
|
|
</div>
|
|
|
|
<h2 id="discounts">Discount codes</h2>
|
|
<p>Four kinds:</p>
|
|
|
|
<table class="t">
|
|
<thead><tr><th>Kind</th><th>What it does</th></tr></thead>
|
|
<tbody>
|
|
<tr><td><code>percent</code></td><td>Buyer appends <code>?code=FOUNDERS50</code> to the purchase URL; price drops by N%.</td></tr>
|
|
<tr><td><code>fixed_sats</code></td><td>Like above, but a flat amount comes off. Denominated in the code’s <code>discount_currency</code> (sats / USD / EUR), so the same code can sit on top of multi-currency products.</td></tr>
|
|
<tr><td><code>set_price</code></td><td>Overrides the tier price with a flat number, regardless of base. Useful for "first 100 buyers at 25k sats" promos where you want the price to be a specific round number rather than a percentage off.</td></tr>
|
|
<tr><td><code>free_license</code></td><td>No payment at all. Buyer redeems the code via <code>POST /v1/redeem</code> and gets a signed license back.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<p>Codes can be capped at N uses, dated to expire, restricted to one product (and optionally to a <strong>subset of policies</strong> on that product, e.g. "applies to Pro and Max but not Basic"), and tagged with a referrer label so you can see which campaign drove which sales in the audit log.</p>
|
|
<p>Codes can also be marked <strong>featured</strong>: a "launch special" mode. A featured code:</p>
|
|
<ul>
|
|
<li>Renders a diagonal "LAUNCH SPECIAL" ribbon + struck-through original price on the matching tier cards on the buy page.</li>
|
|
<li>Auto-applies for buyers who don’t type any code, with the input pre-filled so they can see what’s been applied.</li>
|
|
<li>Stops surfacing once it hits its <code>max_uses</code> cap or expires: the ribbon disappears and pricing reverts to standard automatically.</li>
|
|
</ul>
|
|
<p>Operator-typed codes always take precedence: a buyer who pastes a non-featured code in the form gets that code instead of the auto-applied featured one.</p>
|
|
|
|
<h2 id="revocation">Revocation strategy</h2>
|
|
<p>This is the one piece of the architecture that requires a design decision from you.</p>
|
|
<p>Because verification is offline, a license that was once issued continues to verify forever, even if you mark it as revoked in the admin UI. The verifier in your app doesn’t know about your admin actions.</p>
|
|
<p>You have three options:</p>
|
|
|
|
<ul>
|
|
<li><strong>Don’t support revocation at all.</strong> Many indie developers do this. Once a key is sold, it stays valid.</li>
|
|
<li><strong>Periodic online check.</strong> Your app fetches a small revocation list from your Keysat (or a CDN you point at it) once a week / month. Adds a "soft-online" requirement.</li>
|
|
<li><strong>Short-lived licenses with renewal.</strong> Issue 30-day licenses; the app fetches a fresh signed token before expiry. Recurring renewals are first-class in v0.2: define a policy with <code>is_recurring=true</code> + <code>renewal_period_days</code> and Keysat handles the cycle (invoice → settle → re-sign → webhook).</li>
|
|
</ul>
|
|
|
|
<div class="callout">
|
|
<i data-lucide="key-round"></i>
|
|
<p><strong>You decide the policy.</strong> Keysat doesn’t force a particular revocation model. The default is no revocation. That’s the simplest, sovereign-by-default choice. If you need stronger guarantees, layer them on with the patterns above.</p>
|
|
</div>
|
|
|
|
<h2 id="operator-tiers">Operator tiers</h2>
|
|
<p>Keysat itself ships under a tiered self-license. The daemon runs out of the box at the free <strong>Creator</strong> tier with caps that are generous for a solo developer; paid <strong>Pro</strong> and <strong>Patron</strong> tiers lift caps and unlock recurring billing + the Zaprite payment gateway. Caps are enforced by the daemon at create-time only; existing resources are always grandfathered if you downgrade.</p>
|
|
<p>As of this writing, Creator caps at <strong>5 products / 5 policies per product / 10 active discount codes</strong>, and Pro / Patron are unlimited. The exact tier list, prices, entitlements, and any active launch-special discount are operator-controlled on the master Keysat and may change. The canonical sources are:</p>
|
|
<ul>
|
|
<li>The live tier cards on <a href="https://keysat.xyz#tiers">keysat.xyz</a> (rendered dynamically from the master Keysat).</li>
|
|
<li>The <a href="pricing.html">pricing page</a> on these docs for the human-readable breakdown.</li>
|
|
<li><code>GET https://licensing.keysat.xyz/v1/products/keysat/policies</code> for the machine-readable shape (entitlements, marketing bullets, featured discount, etc.).</li>
|
|
<li>Your local daemon’s <code>GET /v1/admin/tier</code> for current tier + caps + usage from inside the admin context.</li>
|
|
</ul>
|
|
|
|
<h2 id="next">Where to next</h2>
|
|
<div class="next-grid">
|
|
<a class="next-card" href="install.html">
|
|
<span class="eyebrow">Step 1 for operators</span>
|
|
<h4>Install & setup →</h4>
|
|
<p>Get Keysat running on your Start9, connect BTCPay, define your first product.</p>
|
|
</a>
|
|
<a class="next-card" href="integrate.html">
|
|
<span class="eyebrow">Step 1 for integrators</span>
|
|
<h4>Integrate the SDK →</h4>
|
|
<p>Embed your public key, add the SDK to your app, verify a license offline.</p>
|
|
</a>
|
|
<a class="next-card" href="agent.html">
|
|
<span class="eyebrow">Step 1 for agent builders</span>
|
|
<h4>Agent integration →</h4>
|
|
<p>Operate your Keysat instance programmatically. OpenAPI spec, scoped keys, webhooks, recipes.</p>
|
|
</a>
|
|
</div>
|
|
</main>
|
|
|
|
<aside class="toc">
|
|
<div class="label">On this page</div>
|
|
<a href="#architecture">Architecture</a>
|
|
<a href="#products-policies">Products & policies</a>
|
|
<a href="#merchant-profiles">Merchant profiles</a>
|
|
<a href="#discounts">Discount codes</a>
|
|
<a href="#revocation">Revocation strategy</a>
|
|
<a href="#operator-tiers">Operator tiers</a>
|
|
<a href="#next">Where to next</a>
|
|
</aside>
|
|
</div>
|
|
|
|
<script src="https://unpkg.com/lucide@latest"></script>
|
|
<script>lucide.createIcons();</script>
|
|
<script src="docs.js"></script>
|
|
</body>
|
|
</html>
|