Compare commits
10 Commits
ac5ead5124
...
87fd4f32e3
| Author | SHA1 | Date | |
|---|---|---|---|
 Keysat
|
87fd4f32e3 | ||
|
Keysat
|
348a0b9f13 | ||
|
Keysat
|
9a881f5f06 | ||
|
Keysat
|
fe96fe2091 | ||
|
Keysat
|
23aa121afb | ||
|
Keysat
|
95a11666d7 | ||
|
Keysat
|
8e55b6ee8b | ||
|
Keysat
|
9e4c36c05b | ||
|
Keysat
|
11760cc295 | ||
|
Keysat
|
19a969f797 |
+309
@@ -0,0 +1,309 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>Keysat Docs: Agent integration</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">Introduction</a>
|
||||
<a href="install.html">Install & setup</a>
|
||||
<a href="integrate.html">Integrate the SDK</a>
|
||||
<a href="agent.html" class="active">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#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 · Agent integration</div>
|
||||
<h1>Agent integration guide.</h1>
|
||||
<p class="lead">How to build agents, bots, and automation that operate a Keysat instance. Keysat was designed from the start to be agent-friendly: the admin API uses plain HTTP + JSON with Bearer-token auth, an OpenAPI 3.1 spec drives discovery, scoped API keys grant least-privilege access without exposing the master credential, errors carry stable machine-readable codes, and webhooks let an agent react to events instead of polling.</p>
|
||||
<p>This guide covers the <em>operator side</em> of Keysat: running, configuring, and performing day-to-day operations. For the <em>buyer side</em> (validating licenses inside your app), see <a href="integrate.html">Integrate the SDK</a>.</p>
|
||||
|
||||
<h2 id="quick-start">Quick start</h2>
|
||||
<pre><code># 1. Discover the API surface
|
||||
curl https://your-keysat-host/v1/openapi.json
|
||||
|
||||
# 2. Generate a scoped API key (admin UI: Settings → API keys, or via curl)
|
||||
curl -X POST https://your-keysat-host/v1/admin/api-keys \
|
||||
-H "Authorization: Bearer $MASTER_ADMIN_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"label":"Support bot","role":"support"}'
|
||||
# Response includes `token: ks_...`. Save it. It's only shown once.
|
||||
|
||||
# 3. Use the scoped key
|
||||
curl https://your-keysat-host/v1/admin/licenses?status=active \
|
||||
-H "Authorization: Bearer ks_..."</code></pre>
|
||||
|
||||
<h2 id="auth">Authentication</h2>
|
||||
<p>All admin endpoints use HTTP Bearer auth:</p>
|
||||
<pre><code>Authorization: Bearer <token></code></pre>
|
||||
<p>Two kinds of tokens are accepted.</p>
|
||||
|
||||
<p><strong>Master admin API key</strong>: the env-configured <code>KEYSAT_ADMIN_API_KEY</code> (visible in StartOS Actions → Show credentials on first install). Full access to every endpoint. This is the operator's credential. Don't hand it to agents.</p>
|
||||
|
||||
<p><strong>Scoped API keys</strong>: additional tokens generated in admin UI → Settings → API keys. Each carries a role that bounds what it can do. Format: <code>ks_<43 chars></code>. Operators can revoke any scoped key from the same UI; revoked tokens stop working immediately.</p>
|
||||
|
||||
<h3>Role to scope mapping</h3>
|
||||
<table>
|
||||
<thead><tr><th>Role</th><th>What it can do</th></tr></thead>
|
||||
<tbody>
|
||||
<tr><td><code>read-only</code></td><td>List / get every resource. Mutate nothing.</td></tr>
|
||||
<tr><td><code>license-issuer</code></td><td>All <code>read-only</code> scopes + issue / revoke / suspend / change-tier on licenses. Cannot touch products, policies, or codes.</td></tr>
|
||||
<tr><td><code>support</code></td><td>All <code>license-issuer</code> scopes + cancel subscriptions + force-deactivate machines.</td></tr>
|
||||
<tr><td><code>full-admin</code></td><td>Every scope. Equivalent to the master key for most endpoints.</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>Endpoints that touch settings (operator name, payment provider connections, self-license activation, scoped API key management) always require the master admin key. A <code>full-admin</code> scoped key cannot, for example, generate another scoped key. That's a self-defeating elevation path.</p>
|
||||
|
||||
<h2 id="discovery">Discovering the API</h2>
|
||||
<p>Two complementary discovery mechanisms.</p>
|
||||
|
||||
<h3>OpenAPI 3.1 spec</h3>
|
||||
<p><code>GET /v1/openapi.json</code>. Unauthenticated. Returns a curated spec covering the agent-relevant subset of endpoints. Use this with:</p>
|
||||
<ul>
|
||||
<li><strong>OpenAI Custom GPTs</strong>: paste the URL as an Action.</li>
|
||||
<li><strong>OpenAI Assistants / Functions</strong>: feed the spec to tool definition generators.</li>
|
||||
<li><strong>Claude tool use</strong>: derive your <code>tools</code> array from the spec; Claude Code agents can <code>WebFetch</code> the spec at runtime.</li>
|
||||
<li><strong>LangChain / AutoGen / Smolagents</strong>: use their OpenAPI loaders.</li>
|
||||
<li><strong>Code generation</strong>: <code>openapi-generator-cli generate -i /v1/openapi.json -g python -o ./client</code>.</li>
|
||||
</ul>
|
||||
<p>The spec is a stable agent surface, not auto-derived from handler signatures. We commit to keeping documented endpoints and field shapes stable across minor releases.</p>
|
||||
|
||||
<h3>Embedded endpoint listing</h3>
|
||||
<p>This guide's <a href="#workflows">Common workflows</a> section below covers the most common agent tasks with copy-paste examples.</p>
|
||||
|
||||
<h2 id="envelope">Response envelope conventions</h2>
|
||||
<p>Every error response uses the same JSON envelope:</p>
|
||||
<pre><code>{
|
||||
"ok": false,
|
||||
"error": "tier_cap",
|
||||
"message": "Your Creator tier allows up to 5 products. You're at 5...",
|
||||
"upgrade_url": "https://licensing.keysat.xyz/buy/keysat?policy=pro"
|
||||
}</code></pre>
|
||||
<p><code>error</code> is a stable machine-readable code; <code>message</code> is human-readable. The <code>upgrade_url</code> field appears on 402 (tier cap) responses so a UI can render an upgrade CTA without parsing message strings.</p>
|
||||
|
||||
<h3>Error codes</h3>
|
||||
<table>
|
||||
<thead><tr><th>HTTP</th><th><code>error</code> code</th><th>When</th></tr></thead>
|
||||
<tbody>
|
||||
<tr><td>400</td><td><code>bad_request</code></td><td>Malformed body, missing required field, invalid enum value</td></tr>
|
||||
<tr><td>401</td><td><code>unauthorized</code></td><td>No <code>Authorization: Bearer</code> header</td></tr>
|
||||
<tr><td>403</td><td><code>forbidden</code></td><td>Wrong token, revoked scoped key, role doesn't grant required scope</td></tr>
|
||||
<tr><td>404</td><td><code>not_found</code></td><td>Resource id doesn't exist</td></tr>
|
||||
<tr><td>409</td><td><code>conflict</code></td><td>Slug collision, delete-with-references blocked, etc.</td></tr>
|
||||
<tr><td>402</td><td><code>tier_cap</code></td><td>Operator's self-tier doesn't include the required entitlement</td></tr>
|
||||
<tr><td>429</td><td><code>rate_limited</code></td><td>Rate limit hit (e.g. /v1/recover, /v1/validate)</td></tr>
|
||||
<tr><td>502</td><td><code>upstream_error</code></td><td>BTCPay / Zaprite call failed</td></tr>
|
||||
<tr><td>503</td><td><code>service_unavailable</code> / <code>btcpay_not_configured</code></td><td>Provider not yet connected</td></tr>
|
||||
<tr><td>500</td><td><code>internal_error</code></td><td>Bug. Includes a trace id in logs; report it.</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h3>Validate response</h3>
|
||||
<p><code>POST /v1/validate</code> is the one endpoint that returns 200 in all cases. Inspect <code>ok</code> + <code>reason</code>:</p>
|
||||
<table>
|
||||
<thead><tr><th><code>reason</code></th><th>Meaning</th></tr></thead>
|
||||
<tbody>
|
||||
<tr><td><code>bad_signature</code></td><td>Signature doesn't verify against the trust-root pubkey</td></tr>
|
||||
<tr><td><code>not_found</code></td><td>License key not in the daemon's DB</td></tr>
|
||||
<tr><td><code>revoked</code></td><td>Operator revoked it</td></tr>
|
||||
<tr><td><code>suspended</code></td><td>Operator suspended it (reversible)</td></tr>
|
||||
<tr><td><code>expired</code></td><td>Past <code>expires_at</code></td></tr>
|
||||
<tr><td><code>fingerprint_mismatch</code></td><td>Different machine than the one bound on first activate</td></tr>
|
||||
<tr><td><code>product_mismatch</code></td><td>License is for a different product than the caller asserted</td></tr>
|
||||
<tr><td><code>machine_cap_exceeded</code></td><td>Activating this fingerprint would exceed <code>max_machines</code></td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h2 id="workflows">Common workflows</h2>
|
||||
|
||||
<h3>Issue a comp license</h3>
|
||||
<pre><code>curl -X POST $KS/v1/admin/licenses \
|
||||
-H "Authorization: Bearer ks_..." \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"product_slug": "recap",
|
||||
"policy_slug": "pro",
|
||||
"buyer_email": "alice@example.com",
|
||||
"buyer_note": "Conference speaker comp"
|
||||
}'</code></pre>
|
||||
<p>Returns the issued license object including <code>license_key</code>. The buyer pastes the key into their app; subsequent validate calls return <code>ok: true</code> with the policy's entitlements.</p>
|
||||
<p><em>Scope required: <code>licenses:write</code> (any role except <code>read-only</code>).</em></p>
|
||||
|
||||
<h3>Revoke a license</h3>
|
||||
<pre><code>curl -X POST $KS/v1/admin/licenses/$LICENSE_ID/revoke \
|
||||
-H "Authorization: Bearer ks_..." \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"reason":"refund issued"}'</code></pre>
|
||||
<p>Idempotent. The next online validate from the buyer's app returns <code>reason: revoked</code>.</p>
|
||||
<p><em>Scope required: <code>licenses:write</code>.</em></p>
|
||||
|
||||
<h3>Find a license by email</h3>
|
||||
<pre><code>curl "$KS/v1/admin/licenses?buyer_email=alice@example.com" \
|
||||
-H "Authorization: Bearer ks_..."</code></pre>
|
||||
<p>Returns matching licenses (without the <code>license_key</code> field, which is only returned on issue / recover). Use the <code>id</code> for follow-up operations.</p>
|
||||
<p><em>Scope required: <code>licenses:read</code>.</em></p>
|
||||
|
||||
<h3>Cancel a buyer's subscription</h3>
|
||||
<pre><code># Look up the subscription id first (filter by license_id if you have it)
|
||||
curl "$KS/v1/admin/subscriptions?status=active" \
|
||||
-H "Authorization: Bearer ks_..."
|
||||
|
||||
# Then cancel
|
||||
curl -X POST $KS/v1/admin/subscriptions/$SUB_ID/cancel \
|
||||
-H "Authorization: Bearer ks_..." \
|
||||
-d '{"reason":"buyer requested"}'</code></pre>
|
||||
<p>License stays valid through the current cycle's <code>expires_at</code>. Renewal worker stops issuing new invoices.</p>
|
||||
<p><em>Scope required: <code>subscriptions:write</code>.</em></p>
|
||||
|
||||
<h3>Free a machine seat</h3>
|
||||
<pre><code>curl -X POST $KS/v1/admin/machines/$MACHINE_ID/deactivate \
|
||||
-H "Authorization: Bearer ks_..." \
|
||||
-d '{"reason":"buyer moved devices"}'</code></pre>
|
||||
<p>The seat opens up. The buyer's next validate from any machine takes the freed seat.</p>
|
||||
<p><em>Scope required: <code>machines:write</code>.</em></p>
|
||||
|
||||
<h3>Programmatic tier change (comp upgrade)</h3>
|
||||
<pre><code>curl -X POST $KS/v1/admin/licenses/$LICENSE_ID/change-tier \
|
||||
-H "Authorization: Bearer ks_..." \
|
||||
-d '{
|
||||
"target_policy_slug": "pro",
|
||||
"reason": "support resolution"
|
||||
}'</code></pre>
|
||||
<p>Always applies as comp (no invoice) from the admin path. Buyer-initiated paid upgrades go through <code>/v1/upgrade</code> (different endpoint, signed-license auth).</p>
|
||||
<p><em>Scope required: <code>licenses:write</code>.</em></p>
|
||||
|
||||
<h2 id="webhooks">Webhooks: react to events instead of polling</h2>
|
||||
<p>Configure webhook endpoints in admin UI → Webhooks. The daemon POSTs JSON payloads, HMAC-SHA256 signed with the endpoint's secret, on these events:</p>
|
||||
<table>
|
||||
<thead><tr><th>Event</th><th>Fires on</th></tr></thead>
|
||||
<tbody>
|
||||
<tr><td><code>license.issued</code></td><td>New license minted (purchase, comp, redeem)</td></tr>
|
||||
<tr><td><code>license.revoked</code> / <code>license.suspended</code> / <code>license.unsuspended</code></td><td>Admin operations</td></tr>
|
||||
<tr><td><code>license.tier_changed</code></td><td>Tier upgrade/downgrade applied</td></tr>
|
||||
<tr><td><code>invoice.paid</code></td><td>A BTCPay / Zaprite invoice settled</td></tr>
|
||||
<tr><td><code>subscription.renewal_pending</code></td><td>Renewal worker created a fresh invoice</td></tr>
|
||||
<tr><td><code>subscription.renewal_skipped</code></td><td>Renewal skipped (e.g. policy archived)</td></tr>
|
||||
<tr><td><code>subscription.cancelled</code></td><td>Buyer or admin cancelled</td></tr>
|
||||
<tr><td><code>subscription.lapsed</code></td><td>Past-due grace expired</td></tr>
|
||||
<tr><td><code>machine.activated</code></td><td>First validate from a new fingerprint</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<p>Verify signatures:</p>
|
||||
<pre><code>import hmac, hashlib
|
||||
|
||||
def verify(body_bytes: bytes, signature_header: str, secret: str) -> bool:
|
||||
expected = hmac.new(secret.encode(), body_bytes, hashlib.sha256).hexdigest()
|
||||
return hmac.compare_digest(expected, signature_header)</code></pre>
|
||||
<p>The header is <code>X-Keysat-Signature</code>. Failed deliveries retry with exponential backoff up to 10 attempts; permanently-failed deliveries land in the DLQ visible at admin UI → Webhooks → Failed.</p>
|
||||
|
||||
<h2 id="robust">Designing a robust agent</h2>
|
||||
<p>A few patterns that work well in practice.</p>
|
||||
|
||||
<h3>Idempotency</h3>
|
||||
<p>The daemon's mutation endpoints are idempotent where they can be. Revoke, suspend, unsuspend, archive, unarchive, subscription cancel. All return success on the second call without changing state. Your agent can safely retry on network errors.</p>
|
||||
|
||||
<h3>Pagination</h3>
|
||||
<p>List endpoints return up to ~100 rows by default. Use <code>?limit=N</code> and <code>?offset=N</code> for larger result sets. The OpenAPI spec documents the limits per endpoint.</p>
|
||||
|
||||
<h3>Rate limits</h3>
|
||||
<p>The admin endpoints have no per-IP rate limit today. Operators are trusted. The public endpoints (<code>/v1/validate</code>, <code>/v1/recover</code>) are rate-limited per client IP (10/min for <code>/recover</code>; <code>/validate</code> is unlimited but a reasonable agent calls it once per app boot + once per hour).</p>
|
||||
|
||||
<h3>Master key handling</h3>
|
||||
<p>If your automation needs <code>full-admin</code> because it touches operator-only operations (creating other API keys, changing payment providers), use the master key from a secret manager. If it can stay within license / product / policy operations, <strong>always use a scoped key</strong>. Operators can revoke a compromised scoped key without rotating the master credential.</p>
|
||||
|
||||
<h3>Backoff on 5xx</h3>
|
||||
<p><code>internal_error</code> (500) is a bug or a transient DB lock. Retry with exponential backoff (1s, 2s, 4s, 8s, give up). Don't retry on 4xx. Those are deterministic client errors.</p>
|
||||
|
||||
<h2 id="recipe">Concrete recipe: "Comp a license to anyone who emails support@"</h2>
|
||||
<pre><code>import os, requests, imaplib, email
|
||||
|
||||
KS = os.environ["KEYSAT_URL"]
|
||||
TOKEN = os.environ["KEYSAT_API_KEY"] # license-issuer-scoped key
|
||||
|
||||
def issue_comp_license(buyer_email: str, product_slug: str, reason: str) -> str:
|
||||
r = requests.post(
|
||||
f"{KS}/v1/admin/licenses",
|
||||
headers={"Authorization": f"Bearer {TOKEN}"},
|
||||
json={
|
||||
"product_slug": product_slug,
|
||||
"policy_slug": "default",
|
||||
"buyer_email": buyer_email,
|
||||
"buyer_note": reason,
|
||||
},
|
||||
timeout=10,
|
||||
)
|
||||
r.raise_for_status()
|
||||
return r.json()["license_key"]
|
||||
|
||||
# Poll IMAP, parse incoming requests, call issue_comp_license, reply with the key</code></pre>
|
||||
<p>That's the entire pattern. The agent doesn't need full admin, just the license-issuer role. If it ever gets compromised, you revoke the scoped key in the admin UI and generate a new one in 30 seconds.</p>
|
||||
|
||||
<h2 id="not-exposed">What's NOT exposed to agents</h2>
|
||||
<p>Some operations are deliberately operator-only and not accessible to any scoped key, including <code>full-admin</code>:</p>
|
||||
<ul>
|
||||
<li>Generating / revoking scoped API keys (<code>/v1/admin/api-keys</code>)</li>
|
||||
<li>Connecting / disconnecting payment providers</li>
|
||||
<li>Setting the operator name</li>
|
||||
<li>Activating the self-license (<code>/v1/admin/self-license</code>)</li>
|
||||
<li>Resetting the analytics install_uuid</li>
|
||||
<li>Changing the web UI password (StartOS Action only)</li>
|
||||
</ul>
|
||||
<p>These all require the master <code>KEYSAT_ADMIN_API_KEY</code>. The reasoning: an agent that can rotate its own credentials, connect arbitrary payment processors, or change the operator identity is no longer bounded by the role it was given.</p>
|
||||
|
||||
<h2 id="feedback">Help us improve this guide</h2>
|
||||
<p>The OpenAPI spec is the source of truth for the API surface. This guide is a hand-curated overlay focused on the workflows we've seen agents actually need. If you're building something the spec covers but this guide doesn't make obvious, open an issue at <a href="https://github.com/keysat-xyz/keysat">github.com/keysat-xyz/keysat</a> with the workflow shape and we'll add it.</p>
|
||||
</main>
|
||||
|
||||
<aside class="toc">
|
||||
<div class="label">On this page</div>
|
||||
<a href="#quick-start">Quick start</a>
|
||||
<a href="#auth">Authentication</a>
|
||||
<a href="#discovery">Discovering the API</a>
|
||||
<a href="#envelope">Response envelope</a>
|
||||
<a href="#workflows">Common workflows</a>
|
||||
<a href="#webhooks">Webhooks</a>
|
||||
<a href="#robust">Designing a robust agent</a>
|
||||
<a href="#recipe">Recipe: comp-license bot</a>
|
||||
<a href="#not-exposed">Not exposed to agents</a>
|
||||
</aside>
|
||||
</div>
|
||||
|
||||
<script src="docs.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,49 @@
|
||||
// Shared docs-site behaviors. Loaded at the bottom of every page.
|
||||
//
|
||||
// Sidebar active-pill sync: the .active class on sidebar links is
|
||||
// baked into each HTML file as a baseline (page-level link only),
|
||||
// which means clicking an in-page anchor link (e.g. "Discount codes"
|
||||
// → index.html#discounts) leaves the pill stuck on whatever the
|
||||
// statically-marked page link was. This script keeps the active
|
||||
// state in sync with the current URL hash so the pill follows
|
||||
// what the user clicked.
|
||||
(function () {
|
||||
var sidebarLinks = Array.prototype.slice.call(
|
||||
document.querySelectorAll('aside.side a')
|
||||
);
|
||||
if (!sidebarLinks.length) return;
|
||||
|
||||
var currentFile = (location.pathname.split('/').pop() || 'index.html');
|
||||
|
||||
function findActive(hash) {
|
||||
var desired = hash ? (currentFile + hash) : currentFile;
|
||||
var match = null;
|
||||
sidebarLinks.forEach(function (a) {
|
||||
if (a.getAttribute('href') === desired) match = a;
|
||||
});
|
||||
if (match) return match;
|
||||
// Fallback: bare current-file link when no hash matches
|
||||
sidebarLinks.forEach(function (a) {
|
||||
if (a.getAttribute('href') === currentFile) match = a;
|
||||
});
|
||||
return match;
|
||||
}
|
||||
|
||||
function setActive(link) {
|
||||
if (!link) return;
|
||||
sidebarLinks.forEach(function (a) { a.classList.remove('active'); });
|
||||
link.classList.add('active');
|
||||
}
|
||||
|
||||
setActive(findActive(location.hash));
|
||||
|
||||
window.addEventListener('hashchange', function () {
|
||||
setActive(findActive(location.hash));
|
||||
});
|
||||
|
||||
sidebarLinks.forEach(function (a) {
|
||||
a.addEventListener('click', function () {
|
||||
setActive(a);
|
||||
});
|
||||
});
|
||||
})();
|
||||
+57
-25
@@ -3,22 +3,15 @@
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>Keysat Docs — Introduction</title>
|
||||
<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="index.html" class="brand"><img src="assets/keysat-mark.svg" alt=""><span>Keysat</span></a>
|
||||
<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>
|
||||
<nav>
|
||||
<a href="install.html">Install</a>
|
||||
<a href="integrate.html">Integrate</a>
|
||||
<a href="wire-format.html">Wire format</a>
|
||||
<a href="operate.html">Operate</a>
|
||||
<a href="https://keysat.xyz">Marketing</a>
|
||||
</nav>
|
||||
</div>
|
||||
|
||||
<div class="layout">
|
||||
@@ -28,6 +21,7 @@
|
||||
<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>
|
||||
@@ -39,8 +33,11 @@
|
||||
<div class="group">
|
||||
<div class="glabel">Reference</div>
|
||||
<a href="wire-format.html">Wire format</a>
|
||||
<a href="integrate.html#api">Admin API</a>
|
||||
<a href="integrate.html#sdks">SDKs</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>
|
||||
@@ -53,7 +50,8 @@
|
||||
<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, the Bitcoin payment via BTCPay, and a signed license for each buyer. 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 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>
|
||||
|
||||
@@ -68,14 +66,19 @@
|
||||
<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>
|
||||
<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>
|
||||
@@ -87,7 +90,7 @@
|
||||
|
||||
<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 in sats.</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">
|
||||
@@ -97,42 +100,64 @@
|
||||
<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>entitlements</code></td><td>Free-form list of feature flags baked into the signed key (e.g. <code>core</code>, <code>sync</code>, <code>export</code>).</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>Each product has one policy slugged <code>default</code> — that’s the one consumed by the public purchase URL. You can attach additional named policies for manual issuance: a longer-duration "Lifetime" policy you hand out at conferences, a richer-entitlement "Pro" policy for upsells, etc.</p>
|
||||
<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="discounts">Discount codes</h2>
|
||||
<p>Three kinds:</p>
|
||||
<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 sat amount comes off.</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 a single product, and tagged with a referrer label so you can see which campaign drove which sales in the audit log.</p>
|
||||
<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>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. Refunds are still possible — you send sats back via BTCPay; the key still works but the customer agreed to stop using it.</li>
|
||||
<li><strong>Don’t support revocation at all.</strong> Many indie developers do this. Once a key is sold, it stays valid. Refunds are still possible. You send sats back via BTCPay; the key still works but the customer agreed to stop using it.</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. v0.2 will ship recurring renewals as a first-class flow.</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>
|
||||
<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">
|
||||
@@ -145,6 +170,11 @@
|
||||
<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>
|
||||
|
||||
@@ -154,11 +184,13 @@
|
||||
<a href="#products-policies">Products & policies</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>
|
||||
|
||||
+31
-30
@@ -3,22 +3,15 @@
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>Keysat Docs — Install & setup</title>
|
||||
<title>Keysat Docs: Install & setup</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="index.html" class="brand"><img src="assets/keysat-mark.svg" alt=""><span>Keysat</span></a>
|
||||
<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>
|
||||
<nav>
|
||||
<a href="install.html" class="active">Install</a>
|
||||
<a href="integrate.html">Integrate</a>
|
||||
<a href="wire-format.html">Wire format</a>
|
||||
<a href="operate.html">Operate</a>
|
||||
<a href="https://keysat.xyz">Marketing</a>
|
||||
</nav>
|
||||
</div>
|
||||
|
||||
<div class="layout">
|
||||
@@ -28,6 +21,7 @@
|
||||
<a href="index.html">Introduction</a>
|
||||
<a href="install.html" class="active">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>
|
||||
@@ -39,8 +33,11 @@
|
||||
<div class="group">
|
||||
<div class="glabel">Reference</div>
|
||||
<a href="wire-format.html">Wire format</a>
|
||||
<a href="integrate.html#api">Admin API</a>
|
||||
<a href="integrate.html#sdks">SDKs</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>
|
||||
@@ -62,7 +59,7 @@
|
||||
<li>About 2 GB of free disk for Keysat itself; BTCPay’s requirements are larger and depend on your Bitcoin node mode.</li>
|
||||
</ul>
|
||||
|
||||
<h2 id="install">Step 1 — Install Keysat</h2>
|
||||
<h2 id="install">Step 1: Install Keysat</h2>
|
||||
<p>Two ways. Either gets you to the same place.</p>
|
||||
|
||||
<h3>Option A: from the Keysat marketplace (recommended)</h3>
|
||||
@@ -81,11 +78,11 @@
|
||||
|
||||
<p>BTCPay Server is declared as a required dependency. If you don’t have it installed yet, StartOS will prompt you to install it as part of the same flow.</p>
|
||||
|
||||
<h2 id="operator-name">Step 2 — Set your operator name</h2>
|
||||
<p>Open the Keysat service page in StartOS. Go to <strong>Actions → Set operator name</strong>. Pick a short label that identifies <em>you</em> as the seller — e.g. "aurora-software", "northpath", "my-name". This shows up on the public purchase pages and in the audit log.</p>
|
||||
<h2 id="operator-name">Step 2: Set your operator name</h2>
|
||||
<p>Open the Keysat service page in StartOS. Go to <strong>Actions → Set operator name</strong>. Pick a short label that identifies <em>you</em> as the seller, e.g. "aurora-software", "northpath", "my-name". This shows up on the public purchase pages and in the audit log.</p>
|
||||
<p>This change is live-reloaded; you don’t need to restart the service.</p>
|
||||
|
||||
<h2 id="connect-btcpay">Step 3 — Connect BTCPay</h2>
|
||||
<h2 id="connect-btcpay">Step 3: Connect BTCPay</h2>
|
||||
<p>Make sure BTCPay Server is running and has at least one <strong>store</strong> with a configured <strong>payment method</strong> (on-chain wallet or Lightning node). Without a payment method, BTCPay will reject Keysat’s invoice creation.</p>
|
||||
|
||||
<p>In Keysat’s service page, click <strong>Actions → Connect BTCPay</strong>. You’ll be redirected to BTCPay’s authorize page, where you grant Keysat the permissions it needs:</p>
|
||||
@@ -118,7 +115,7 @@ payment_methods: <span class="s">[BTC-OnChain, BTC-LightningNetwork]</span></pre
|
||||
|
||||
<p>If <code>payment_methods</code> is empty, head back to BTCPay and configure at least one before continuing.</p>
|
||||
|
||||
<h2 id="admin-key">Step 4 — Get your admin API key</h2>
|
||||
<h2 id="admin-key">Step 4: Get your admin API key</h2>
|
||||
<p>Go to <strong>Actions → Show admin API key</strong>. This reveals the 64-hex-character key that gates all <code>/v1/admin/*</code> endpoints, including the admin UI.</p>
|
||||
|
||||
<div class="callout warn">
|
||||
@@ -126,41 +123,44 @@ payment_methods: <span class="s">[BTC-OnChain, BTC-LightningNetwork]</span></pre
|
||||
<p><strong>Treat this key like a password.</strong> Anyone with it can issue, revoke, or read every license you’ve ever sold. Don’t paste it into Slack. Don’t check it into Git.</p>
|
||||
</div>
|
||||
|
||||
<h2 id="admin-ui">Step 5 — Open the admin UI</h2>
|
||||
<h2 id="admin-ui">Step 5: Open the admin UI</h2>
|
||||
<p>Click the <strong>Launch UI</strong> button on Keysat’s service page. (StartOS surfaces this for any service that defines a <code>type: 'ui'</code> interface.) Paste the admin key from the previous step into the sign-in form.</p>
|
||||
|
||||
<p>From here on, you mostly work in the admin UI. The StartOS Actions tab is reserved for setup-only operations (operator name, BTCPay connect/disconnect/check, show admin key).</p>
|
||||
|
||||
<h2 id="first-product">Step 6 — Define your first product</h2>
|
||||
<h2 id="first-product">Step 6: Define your first product</h2>
|
||||
<p>In the admin UI, go to <strong>Products → Create a new product</strong> and fill in:</p>
|
||||
|
||||
<ul>
|
||||
<li><strong>Slug</strong> — lowercase, hyphens, will appear in the public URL. e.g. <code>bitcoin-ticker-pro</code>.</li>
|
||||
<li><strong>Display name</strong> — shown on the buyer’s purchase page and on receipts.</li>
|
||||
<li><strong>Description</strong> — one or two sentences; rendered as plain text.</li>
|
||||
<li><strong>Price (sats)</strong> — an integer. e.g. <code>50000</code> for ~$30 USD at current rates.</li>
|
||||
<li><strong>Slug</strong>: lowercase, hyphens, will appear in the public URL. e.g. <code>bitcoin-ticker-pro</code>.</li>
|
||||
<li><strong>Display name</strong>: shown on the buyer’s purchase page and on receipts.</li>
|
||||
<li><strong>Description</strong>: one or two sentences; rendered as plain text.</li>
|
||||
<li><strong>Price</strong>: the currency picker accepts sats, USD, or EUR. For sats, enter an integer (e.g. <code>50000</code>). For USD/EUR, enter the amount in dollars/euros. Keysat converts to BTC at invoice creation and the buyer pays the locked-in BTC amount.</li>
|
||||
</ul>
|
||||
|
||||
<p>The product is created with no policies attached. Next:</p>
|
||||
|
||||
<h2 id="first-policy">Step 7 — Define a default policy</h2>
|
||||
<p>Go to <strong>Policies → Create a new policy</strong>. Pick the product, then:</p>
|
||||
<h2 id="first-policy">Step 7: Define one or more policies</h2>
|
||||
<p>Go to <strong>Policies → Create a new policy</strong>. Pick the product, then fill in:</p>
|
||||
|
||||
<ul>
|
||||
<li>Set <strong>slug</strong> to <code>default</code>. This is the policy consumed by the public purchase flow; other slugs are reserved for manual issuance.</li>
|
||||
<li>Set <strong>duration_seconds</strong>. Common choices: <code>0</code> (perpetual), <code>31536000</code> (1 year), <code>2592000</code> (30 days for trials).</li>
|
||||
<li>Set <strong>max_machines</strong>. Use <code>1</code> for single-seat licenses or <code>0</code> for unlimited.</li>
|
||||
<li>Optionally add <strong>entitlements</strong> — comma-separated feature flags. These are baked into the signed key and your app reads them at verify time.</li>
|
||||
<li><strong>Slug</strong>: lowercase id (e.g. <code>basic</code>, <code>pro</code>, <code>annual</code>). Not "special" in any way; the buy page renders a tier picker when a product has two or more public policies, with the initial tier chosen by <code>?policy=<slug></code> in the URL, then by the policy you mark "most popular", then by cheapest.</li>
|
||||
<li><strong>Duration</strong>. Common choices: perpetual, 30 days (trial), 1 year. Recurring subscriptions are a separate toggle on the same form. Flip "Recurring subscription" + set a renewal cadence and Keysat handles the cycle (invoice → settle → re-sign) automatically.</li>
|
||||
<li><strong>Max devices</strong>. <code>1</code> for single-seat, <code>0</code> for unlimited.</li>
|
||||
<li><strong>Entitlements</strong>: pick from the product's catalog (you set up the catalog when you created the product on the previous step). The picked entitlements are baked into the signed license and your app reads them at verify time. Optionally toggle the "hide on buy page" eye icon on any entitlement to drop it from the tier card without un-granting it. Useful for higher tiers that use "Everything in Basic, plus:" marketing copy.</li>
|
||||
<li><strong>Marketing bullets</strong> (optional): operator-authored ✓ items rendered on the tier card alongside the entitlements. Pure marketing copy, not enforced.</li>
|
||||
</ul>
|
||||
|
||||
<h2 id="purchase-url">Step 8 — Share your purchase URL</h2>
|
||||
<p>If you're selling a multi-tier product (e.g. Basic / Pro / Max), repeat this step for each tier. Drag the cards in the Policies grid to set the order shown to buyers.</p>
|
||||
|
||||
<h2 id="purchase-url">Step 8: Share your purchase URL</h2>
|
||||
<p>Your public purchase URL is now live at:</p>
|
||||
|
||||
<pre class="code">https://<your-keysat-host>/buy/<product-slug></pre>
|
||||
|
||||
<p>Buyers hit it, see your product, click "Pay", and BTCPay’s checkout takes over. On payment confirmation, Keysat receives a webhook from BTCPay, signs a license, and emails it to the buyer (if they entered an email) and shows it on the receipt page.</p>
|
||||
|
||||
<p>Test it end-to-end by creating a free-license discount code and redeeming it — the same code path runs, just without the payment leg.</p>
|
||||
<p>Test it end-to-end by creating a free-license discount code and redeeming it: the same code path runs, just without the payment leg.</p>
|
||||
|
||||
<h2 id="next">What’s next</h2>
|
||||
<div class="next-grid">
|
||||
@@ -193,5 +193,6 @@ payment_methods: <span class="s">[BTC-OnChain, BTC-LightningNetwork]</span></pre
|
||||
|
||||
<script src="https://unpkg.com/lucide@latest"></script>
|
||||
<script>lucide.createIcons();</script>
|
||||
<script src="docs.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
+25
-22
@@ -3,22 +3,15 @@
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>Keysat Docs — Integrate the SDK</title>
|
||||
<title>Keysat Docs: Integrate the SDK</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="index.html" class="brand"><img src="assets/keysat-mark.svg" alt=""><span>Keysat</span></a>
|
||||
<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>
|
||||
<nav>
|
||||
<a href="install.html">Install</a>
|
||||
<a href="integrate.html" class="active">Integrate</a>
|
||||
<a href="wire-format.html">Wire format</a>
|
||||
<a href="operate.html">Operate</a>
|
||||
<a href="https://keysat.xyz">Marketing</a>
|
||||
</nav>
|
||||
</div>
|
||||
|
||||
<div class="layout">
|
||||
@@ -28,6 +21,7 @@
|
||||
<a href="index.html">Introduction</a>
|
||||
<a href="install.html">Install & setup</a>
|
||||
<a href="integrate.html" class="active">Integrate the SDK</a>
|
||||
<a href="agent.html">Agent integration</a>
|
||||
</div>
|
||||
<div class="group">
|
||||
<div class="glabel">Concepts</div>
|
||||
@@ -39,8 +33,11 @@
|
||||
<div class="group">
|
||||
<div class="glabel">Reference</div>
|
||||
<a href="wire-format.html">Wire format</a>
|
||||
<a href="integrate.html#api">Admin API</a>
|
||||
<a href="integrate.html#sdks">SDKs</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>
|
||||
@@ -53,23 +50,24 @@
|
||||
<main class="prose">
|
||||
<div class="crumb">Get started · Integrate the SDK</div>
|
||||
<h1>Integrate the SDK.</h1>
|
||||
<p class="lead">Wire Keysat licenses into your software in under an afternoon. The verifier is pure-function, offline, and ships in five lines. What you do with the result — refuse to start without a license, unlock specific features, just show a "supporter" badge — is your call. The SDK is the primitive; the business model is yours.</p>
|
||||
<p class="lead">Wire Keysat licenses into your software in under an afternoon. The verifier is pure-function, offline, and ships in five lines. What you do with the result (refuse to start without a license, unlock specific features, just show a "supporter" badge) is your call. The SDK is the primitive; the business model is yours.</p>
|
||||
|
||||
<h2 id="prereq">Prerequisites</h2>
|
||||
<p>Before you start, you should have:</p>
|
||||
<ul>
|
||||
<li>A Keysat installation running on your Start9 — see <a href="install.html">Install & setup</a>.</li>
|
||||
<li>BTCPay Server connected to Keysat — ditto.</li>
|
||||
<li>A Keysat installation running on your Start9; see <a href="install.html">Install & setup</a>.</li>
|
||||
<li>BTCPay Server connected to Keysat; ditto.</li>
|
||||
<li>At least one product defined in the admin UI.</li>
|
||||
</ul>
|
||||
|
||||
<h2 id="sdks">Pick an SDK</h2>
|
||||
<p>Three official SDKs ship today. They are wire-compatible — a license issued by your Keysat verifies identically in any of them.</p>
|
||||
<p>Four official SDKs ship today. They are wire-compatible. A license issued by your Keysat verifies identically in any of them. Cross-check fixtures in the daemon repo prove each SDK accepts the same bytes the daemon mints.</p>
|
||||
|
||||
<div class="lang-tabs" role="tablist">
|
||||
<button class="active" data-lang="ts">TypeScript</button>
|
||||
<button data-lang="rs">Rust</button>
|
||||
<button data-lang="py">Python</button>
|
||||
<button data-lang="go">Go</button>
|
||||
</div>
|
||||
|
||||
<pre class="code lang-pane" data-lang="ts"><span class="c"># npm</span>
|
||||
@@ -79,16 +77,20 @@ npm install @keysat/licensing-client
|
||||
pnpm add @keysat/licensing-client</pre>
|
||||
<pre class="code lang-pane" data-lang="rs" style="display:none"><span class="c"># Cargo.toml</span>
|
||||
[dependencies]
|
||||
licensing-client = <span class="s">"0.1"</span></pre>
|
||||
keysat-licensing-client = <span class="s">"0.3"</span></pre>
|
||||
<pre class="code lang-pane" data-lang="py" style="display:none"><span class="c"># pip</span>
|
||||
pip install keysat-licensing-client
|
||||
|
||||
<span class="c"># or with poetry</span>
|
||||
poetry add keysat-licensing-client</pre>
|
||||
<pre class="code lang-pane" data-lang="go" style="display:none"><span class="c">// go.mod</span>
|
||||
go get github.com/keysat-xyz/keysat-client-go
|
||||
|
||||
<span class="c">// stdlib only: no third-party Go dependencies</span></pre>
|
||||
|
||||
<p>If your language isn’t covered, see <a href="wire-format.html">Wire format</a>. The format is small and porting takes about an afternoon.</p>
|
||||
|
||||
<h2 id="embed">Step 1 — Embed your public key</h2>
|
||||
<h2 id="embed">Step 1: Embed your public key</h2>
|
||||
<p>In the admin UI, open <strong>Overview</strong> and copy the issuer public key from the "Embed your public key" card. (Or fetch it from <code>GET /v1/issuer/public-key</code>.) Paste it into your application’s source code as a compile-time constant.</p>
|
||||
|
||||
<pre class="code lang-pane" data-lang="ts"><span class="k">const</span> <span class="f">ISSUER_PEM</span> = <span class="s">`-----BEGIN PUBLIC KEY-----
|
||||
@@ -106,7 +108,7 @@ MCowBQYDK2VwAyEAmz7q8r4t1v…h3k2pXq9wL
|
||||
<p><strong>Embed it. Don’t fetch it.</strong> The whole point of offline verification is that your software can’t be tricked by a network-level attacker. If you fetch the public key at runtime, you’re back to trusting a server.</p>
|
||||
</div>
|
||||
|
||||
<h2 id="verify">Step 2 — Verify a license at startup</h2>
|
||||
<h2 id="verify">Step 2: Verify a license at startup</h2>
|
||||
<p>Read the user’s license key from wherever you store it (a file in their data directory, the OS keychain, an env var) and verify it on application start.</p>
|
||||
|
||||
<pre class="code lang-pane" data-lang="ts"><span class="k">import</span> { <span class="f">Verifier</span>, <span class="f">PublicKey</span> } <span class="k">from</span> <span class="s">'@keysat/licensing-client'</span>;
|
||||
@@ -163,7 +165,7 @@ result = verifier.<span class="f">verify</span>(license_key_from_user)
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h2 id="errors">Step 3 — Handle errors gracefully</h2>
|
||||
<h2 id="errors">Step 3: Handle errors gracefully</h2>
|
||||
<p>Verification can fail for benign reasons (the user hasn’t pasted a license yet) or hostile ones (someone tampered with a license file). Distinguish them in your UX:</p>
|
||||
|
||||
<pre class="code lang-pane" data-lang="ts"><span class="k">try</span> {
|
||||
@@ -194,7 +196,7 @@ result = verifier.<span class="f">verify</span>(license_key_from_user)
|
||||
show_input_error()</pre>
|
||||
|
||||
<h2 id="renewals">Renewals & revocation</h2>
|
||||
<p>Keysat licenses are signed at issue time and do not phone home. If a license is revoked in the admin UI, the existing key continues to verify in your app — that’s the trade-off for offline.</p>
|
||||
<p>Keysat licenses are signed at issue time and do not phone home. If a license is revoked in the admin UI, the existing key continues to verify in your app. That’s the trade-off for offline.</p>
|
||||
|
||||
<p>If you need revocation, ship a thin <em>online</em> check that runs on a cadence (e.g. once a week) against your Keysat’s revocation feed:</p>
|
||||
|
||||
@@ -228,7 +230,7 @@ result = verifier.<span class="f">verify</span>(license_key_from_user)
|
||||
|
||||
<div class="callout">
|
||||
<i data-lucide="key-round"></i>
|
||||
<p><strong>You decide the policy.</strong> Many indie developers ship no revocation at all. Once a key is sold, it stays valid — refunds happen offline via BTCPay. That’s perfectly reasonable.</p>
|
||||
<p><strong>You decide the policy.</strong> Many indie developers ship no revocation at all. Once a key is sold, it stays valid. Refunds happen offline via BTCPay. That’s perfectly reasonable.</p>
|
||||
</div>
|
||||
|
||||
<h2 id="api">Admin API</h2>
|
||||
@@ -241,7 +243,7 @@ result = verifier.<span class="f">verify</span>(license_key_from_user)
|
||||
<tr><td><code>POST</code></td><td><code>/v1/admin/products</code></td><td>Create a product.</td></tr>
|
||||
<tr><td><code>POST</code></td><td><code>/v1/admin/policies</code></td><td>Create a policy.</td></tr>
|
||||
<tr><td><code>POST</code></td><td><code>/v1/admin/discount-codes</code></td><td>Create a discount or comp code.</td></tr>
|
||||
<tr><td><code>GET</code></td><td><code>/v1/admin/licenses/search</code></td><td>Find licenses by email, npub, or invoice.</td></tr>
|
||||
<tr><td><code>GET</code></td><td><code>/v1/admin/licenses</code></td><td>List / search licenses by buyer email or BTCPay invoice id. (Backend also supports npub search; the buyer-side npub capture flow is still in progress.)</td></tr>
|
||||
<tr><td><code>POST</code></td><td><code>/v1/admin/licenses/<id>/revoke</code></td><td>Revoke a license.</td></tr>
|
||||
<tr><td><code>POST</code></td><td><code>/v1/admin/webhook-endpoints</code></td><td>Register an outbound webhook.</td></tr>
|
||||
<tr><td><code>GET</code></td><td><code>/v1/admin/audit</code></td><td>Read audit log.</td></tr>
|
||||
@@ -280,5 +282,6 @@ result = verifier.<span class="f">verify</span>(license_key_from_user)
|
||||
b.addEventListener('click', () => setLang(b.dataset.lang));
|
||||
});
|
||||
</script>
|
||||
<script src="docs.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
+139
@@ -0,0 +1,139 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>Keysat Docs: License</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">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#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" class="active">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">Project · License</div>
|
||||
<h1>License.</h1>
|
||||
<p class="lead">Keysat is a hybrid project. The daemon is <strong>source-available</strong> under a custom license; the four SDKs are <strong>open source (MIT)</strong>. The split is intentional: developers integrating Keysat into their own software should never have to think about license compatibility, while operators running the daemon agree to a few common-sense restrictions that keep the project sustainable.</p>
|
||||
|
||||
<h2 id="tldr">TL;DR</h2>
|
||||
<table class="t">
|
||||
<thead><tr><th>Component</th><th>License</th><th>Use freely?</th></tr></thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>Keysat daemon<br><span class="muted" style="font-size:12.5px">(<code>keysat-xyz/keysat</code>)</span></td>
|
||||
<td>Keysat Source-Available License 1.0<br><span class="muted" style="font-size:12.5px">(<code>LicenseRef-Keysat-1.0</code>)</span></td>
|
||||
<td>Audit, run, modify ✓<br>Sell licenses to your own products ✓<br>Redistribute binaries ✗<br>Run as a hosted service for others ✗</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>SDKs<br><span class="muted" style="font-size:12.5px">(<code>keysat-client-{rust,ts,python,go}</code>)</span></td>
|
||||
<td>MIT</td>
|
||||
<td>Anything ✓<br>Including commercial use, redistribution, modification, sublicensing, private use.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Activate-license template<br><span class="muted" style="font-size:12.5px">(<code>keysat-activate-template</code>)</span></td>
|
||||
<td>MIT</td>
|
||||
<td>Anything ✓<br>Copy the buyer-side actions directly into your own StartOS package.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h2 id="why">Why source-available for the daemon?</h2>
|
||||
<p>Two reasons, both pragmatic:</p>
|
||||
<ol>
|
||||
<li><strong>The work has real cost.</strong> Building Keysat takes time. The source-available model lets the project be funded by operators on the Pro / Patron tiers who get value from a maintained, evolving daemon, without forcing every operator onto a paid tier.</li>
|
||||
<li><strong>The "AWS-hosts-our-open-source" failure mode.</strong> Fully open-source self-hosted projects routinely get strip-mined by cloud providers who host them as a managed service and capture the revenue. The daemon license forbids this specific pattern. Everything else is permitted: running your own instance, modifying it, auditing the code, selling licenses for your own products through it.</li>
|
||||
</ol>
|
||||
<p>The SDKs are MIT because they sit inside <em>your</em> software. License compatibility there is critical and the MIT license is the modern default for libraries you embed.</p>
|
||||
|
||||
<h2 id="permitted">What you can do (daemon)</h2>
|
||||
<ul>
|
||||
<li><strong>Audit the source.</strong> Read every line; understand the cryptography, the storage, the API surface.</li>
|
||||
<li><strong>Run an instance on infrastructure you control.</strong> A Start9 box at home, a VPS, a cloud instance: anywhere you deploy it.</li>
|
||||
<li><strong>Modify it for your needs.</strong> Add features, change defaults, integrate it more deeply with your StartOS package. Modifications remain under the same license.</li>
|
||||
<li><strong>Operate it as your private licensing service</strong> to issue signed license keys for software products <em>you</em> sell or distribute. This is the intended use case. Keysat exists for this.</li>
|
||||
<li><strong>Maintain a public fork.</strong> Forks on GitHub are fine as long as they carry the license unchanged and don't enable any of the prohibited uses below.</li>
|
||||
</ul>
|
||||
|
||||
<h2 id="forbidden">What you can't do without prior permission (daemon)</h2>
|
||||
<ul>
|
||||
<li><strong>Distribute compiled binaries to third parties.</strong> Including free of charge. The intent is that operators run Keysat themselves; they don't hand pre-built copies to others.</li>
|
||||
<li><strong>Provide Keysat as a hosted / managed service to third parties.</strong> "Keysat-as-a-Service" run by a cloud provider for a fee, or by anyone other than the operator using it for their own products, is the one pattern explicitly forbidden. Your own customers receiving signed license keys from your instance are <em>not</em> a hosted service. That's the daemon's intended use case.</li>
|
||||
<li><strong>Sell, sublicense, lease, or rent the daemon software itself.</strong> Distinct from selling licenses <em>through</em> the daemon, which is allowed.</li>
|
||||
<li><strong>Remove copyright notices or this license text.</strong></li>
|
||||
</ul>
|
||||
<p>If you have a use case that crosses one of these lines (commercial redistribution, white-label deployment, a managed-service offering), email <a href="mailto:licensing@keysat.xyz">licensing@keysat.xyz</a>. The license isn't designed to be a wall; it's designed to make commercial expansion an explicit conversation rather than an implicit one.</p>
|
||||
|
||||
<h2 id="contributions">Contributions</h2>
|
||||
<p>By submitting code, documentation, designs, or other contributions to the upstream daemon repo, you grant Keysat a perpetual, worldwide, non-exclusive, royalty-free license to use, modify, relicense, and redistribute your contribution under the same license (or any later version). You retain ownership of your contribution; this is a license-back, not an assignment. The full text is in <a href="https://github.com/keysat-xyz/keysat/blob/main/LICENSE">LICENSE Section 4</a>.</p>
|
||||
|
||||
<h2 id="full-text">Full license text</h2>
|
||||
<p>The authoritative text lives at <a href="https://github.com/keysat-xyz/keysat/blob/main/LICENSE">github.com/keysat-xyz/keysat/blob/main/LICENSE</a>. This page is a plain-English summary; the LICENSE file is what governs in any conflict.</p>
|
||||
|
||||
<h2 id="sdks">SDK licenses</h2>
|
||||
<p>Each SDK ships under the MIT License, included verbatim in the <code>LICENSE</code> file of each repo:</p>
|
||||
<ul>
|
||||
<li><a href="https://github.com/keysat-xyz/keysat-client-rust/blob/main/LICENSE">keysat-client-rust</a></li>
|
||||
<li><a href="https://github.com/keysat-xyz/keysat-client-ts/blob/main/LICENSE">keysat-client-ts</a></li>
|
||||
<li><a href="https://github.com/keysat-xyz/keysat-client-python/blob/main/LICENSE">keysat-client-python</a></li>
|
||||
<li><a href="https://github.com/keysat-xyz/keysat-client-go/blob/main/LICENSE">keysat-client-go</a></li>
|
||||
<li><a href="https://github.com/keysat-xyz/keysat-activate-template/blob/main/LICENSE">keysat-activate-template</a></li>
|
||||
</ul>
|
||||
<p>You can use these in any software: open-source, closed-source, commercial, free, anything. The only obligation MIT imposes is preserving the copyright notice when you redistribute the SDK source itself.</p>
|
||||
|
||||
<h2 id="contact">Commercial inquiries</h2>
|
||||
<p>For commercial redistribution, resale, hosted-service rights, white-label deployment, or any other use not expressly granted by the source-available license: <a href="mailto:licensing@keysat.xyz">licensing@keysat.xyz</a>.</p>
|
||||
</main>
|
||||
|
||||
<aside class="toc">
|
||||
<div class="label">On this page</div>
|
||||
<a href="#tldr">TL;DR</a>
|
||||
<a href="#why">Why source-available</a>
|
||||
<a href="#permitted">What you can do</a>
|
||||
<a href="#forbidden">What you can't do</a>
|
||||
<a href="#contributions">Contributions</a>
|
||||
<a href="#full-text">Full license text</a>
|
||||
<a href="#sdks">SDK licenses</a>
|
||||
<a href="#contact">Commercial inquiries</a>
|
||||
</aside>
|
||||
</div>
|
||||
|
||||
<script src="docs.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
+23
-25
@@ -3,22 +3,15 @@
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>Keysat Docs — Operate</title>
|
||||
<title>Keysat Docs: Operate</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="index.html" class="brand"><img src="assets/keysat-mark.svg" alt=""><span>Keysat</span></a>
|
||||
<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>
|
||||
<nav>
|
||||
<a href="install.html">Install</a>
|
||||
<a href="integrate.html">Integrate</a>
|
||||
<a href="wire-format.html">Wire format</a>
|
||||
<a href="operate.html" class="active">Operate</a>
|
||||
<a href="https://keysat.xyz">Marketing</a>
|
||||
</nav>
|
||||
</div>
|
||||
|
||||
<div class="layout">
|
||||
@@ -28,6 +21,7 @@
|
||||
<a href="index.html">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>
|
||||
@@ -39,8 +33,11 @@
|
||||
<div class="group">
|
||||
<div class="glabel">Reference</div>
|
||||
<a href="wire-format.html">Wire format</a>
|
||||
<a href="integrate.html#api">Admin API</a>
|
||||
<a href="integrate.html#sdks">SDKs</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>
|
||||
@@ -56,14 +53,14 @@
|
||||
<p class="lead">Backups, migration, recovery, and the things that go wrong. The "you didn’t expect to need this page until you needed it" page.</p>
|
||||
|
||||
<h2 id="backups">Backups</h2>
|
||||
<p>StartOS handles backups for you. By default, every service in your StartOS install is included in the same backup snapshot — you set the destination once (encrypted external drive, S3-compatible cloud, etc.) and StartOS schedules nightly snapshots.</p>
|
||||
<p>StartOS handles backups for you. By default, every service in your StartOS install is included in the same backup snapshot. You set the destination once (encrypted external drive, S3-compatible cloud, etc.) and StartOS schedules nightly snapshots.</p>
|
||||
|
||||
<p>The Keysat backup payload is intentionally tiny. It contains:</p>
|
||||
|
||||
<ul>
|
||||
<li>The signing keypair (<code>/data/issuer-key.pem</code>).</li>
|
||||
<li>The SQLite database (<code>/data/keysat.db</code>).</li>
|
||||
<li>The SQLite database (<code>/data/keysat.db</code>), which holds the Ed25519 signing keypair in the <code>server_keys</code> table along with all products, policies, licenses, invoices, audit log, webhook subscribers, and operator settings.</li>
|
||||
<li>Migration history.</li>
|
||||
<li>The self-license file at <code>/data/keysat-license.txt</code>, if you've activated a paid Keysat tier.</li>
|
||||
</ul>
|
||||
|
||||
<p>That’s it. No log files (those rotate locally), no caches.</p>
|
||||
@@ -83,25 +80,25 @@
|
||||
<li>On the new Start9, complete first-time setup with a fresh password. Don’t install any services yet.</li>
|
||||
<li>StartOS → Settings → Backups → Restore. Point at the same destination. Pick the most recent snapshot.</li>
|
||||
<li>StartOS restores all services in dependency order. Keysat will restore alongside BTCPay and Bitcoin Core. Bitcoin will need to re-sync if you’re using Bitcoin Core (consider <a href="https://utxo.live">utxo.live</a> for assumeutxo to skip IBD).</li>
|
||||
<li>Once Keysat is running on the new box, your purchase URLs change — the LAN/Tor hostnames are different. Update any links you’ve published.</li>
|
||||
<li>Once Keysat is running on the new box, your purchase URLs change: the LAN/Tor hostnames are different. Update any links you’ve published.</li>
|
||||
</ol>
|
||||
|
||||
<p>The signing keypair restores along with the database, so all previously-issued licenses verify identically against the same public key. You don’t need to re-distribute the public key to your customers.</p>
|
||||
|
||||
<h2 id="signing-key">Rotating the signing key</h2>
|
||||
<p>You generally don’t want to rotate the signing key — doing so invalidates every license you’ve ever issued. v0.1 doesn’t support rotation; the key is generated once at first start and never changed.</p>
|
||||
<p>You generally don’t want to rotate the signing key. Doing so invalidates every license you’ve ever issued. There is no admin-UI affordance for rotation today; the key is generated once on first start (and persisted to the <code>server_keys</code> SQLite table) and stays there for the life of the instance.</p>
|
||||
|
||||
<p>If you absolutely need to rotate (e.g. you suspect the keypair has leaked off the box):</p>
|
||||
|
||||
<ol>
|
||||
<li>Stop Keysat.</li>
|
||||
<li>Move <code>/data/issuer-key.pem</code> aside.</li>
|
||||
<li>Restart Keysat — it will generate a fresh keypair on first run.</li>
|
||||
<li>Re-issue all active licenses to existing customers using the new key. The admin UI doesn’t support bulk re-issuance yet; this is a manual SQL exercise.</li>
|
||||
<li>Push a software update that swaps the embedded public key.</li>
|
||||
<li>Drop the row in the <code>server_keys</code> table (or move the database aside entirely if you also want to start clean).</li>
|
||||
<li>Restart Keysat. It will generate a fresh keypair on first run.</li>
|
||||
<li>Re-issue all active licenses to existing customers using the new key. The admin UI doesn’t support bulk re-issuance yet; this is a manual SQL + scripted-API exercise.</li>
|
||||
<li>Push a software update that swaps the embedded public key in your downstream apps.</li>
|
||||
</ol>
|
||||
|
||||
<p>The cleaner path, for v0.2 onward, will be to support a rolling rotation where both keys verify for a transition period.</p>
|
||||
<p>A future release may support rolling rotation (two keys verifying during a transition window). It's not on the v0.2 / v0.3 roadmap.</p>
|
||||
|
||||
<h2 id="troubleshooting">Troubleshooting</h2>
|
||||
|
||||
@@ -113,7 +110,7 @@
|
||||
<p>BTCPay rejects the invoice request because the store has no configured wallet. Open BTCPay, find your store, and configure either an on-chain wallet or a Lightning node before retrying.</p>
|
||||
|
||||
<h3 id="t-webhook">Webhook deliveries failing</h3>
|
||||
<p>Check the audit log in the admin UI — failed deliveries land there with the response status. Common causes:</p>
|
||||
<p>In the admin UI go to <strong>Webhooks</strong>. Failed deliveries past the 10-attempt retry budget land in the "Failed" filter (the DLQ), with the response status and an inline "Retry" button. The audit log is a secondary source. Common causes:</p>
|
||||
<ul>
|
||||
<li>Endpoint URL no longer reachable. Hit it manually with <code>curl</code> from your laptop to confirm.</li>
|
||||
<li>Endpoint rejecting on signature mismatch. Verify your endpoint is HMAC-validating against the secret you registered with.</li>
|
||||
@@ -121,13 +118,13 @@
|
||||
</ul>
|
||||
|
||||
<h3 id="t-db-locked">"database is locked" errors in logs</h3>
|
||||
<p>Almost always a sign that two daemon instances are racing on the same SQLite file — usually because of a misconfigured supervisor. Confirm only one Keysat container is running. If you’re seeing this on a fresh install with no customizations, file a bug report against the package version you’re running.</p>
|
||||
<p>Almost always a sign that two daemon instances are racing on the same SQLite file, usually because of a misconfigured supervisor. Confirm only one Keysat container is running. If you’re seeing this on a fresh install with no customizations, file a bug report against the package version you’re running.</p>
|
||||
|
||||
<h3 id="t-time-skew">Licenses verifying as "expired" immediately after issue</h3>
|
||||
<p>Clock skew. Either the issuing host or the verifying host has the wrong time. Run NTP. StartOS keeps your Start9 in sync automatically; the issue is usually on the verifier side (e.g. an air-gapped buyer machine).</p>
|
||||
|
||||
<h2 id="logs">Reading the logs</h2>
|
||||
<p>Keysat logs to stdout, captured by StartOS. Tail them from the StartOS dashboard — Service page → Logs → Live tail.</p>
|
||||
<p>Keysat logs to stdout, captured by StartOS. Tail them from the StartOS dashboard: Service page → Logs → Live tail.</p>
|
||||
|
||||
<p>Useful log lines to grep for:</p>
|
||||
|
||||
@@ -147,7 +144,7 @@
|
||||
|
||||
<ul>
|
||||
<li>File an issue at <a href="https://github.com/keysat-xyz/keysat/issues">github.com/keysat-xyz/keysat/issues</a>. Include the package version (visible in the StartOS service page) and any relevant log lines.</li>
|
||||
<li>Email <a href="mailto:licensing@keysat.xyz">licensing@keysat.xyz</a> for security-sensitive issues you don’t want to disclose publicly.</li>
|
||||
<li>For security-sensitive issues you don’t want to disclose publicly, or for paid Patron-tier direct support, email <a href="mailto:licensing@keysat.xyz">licensing@keysat.xyz</a>.</li>
|
||||
</ul>
|
||||
</main>
|
||||
|
||||
@@ -164,5 +161,6 @@
|
||||
|
||||
<script src="https://unpkg.com/lucide@latest"></script>
|
||||
<script>lucide.createIcons();</script>
|
||||
<script src="docs.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
+135
-121
@@ -3,10 +3,11 @@
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>Keysat Docs — Pricing</title>
|
||||
<title>Keysat Docs: Pricing</title>
|
||||
<link rel="icon" type="image/svg+xml" href="assets/favicon.svg">
|
||||
<link rel="stylesheet" href="docs.css">
|
||||
<style>
|
||||
/* Page-local: tier-card grid (only used here). */
|
||||
.tier-grid { display:grid; grid-template-columns:repeat(3, 1fr); gap:18px; margin:24px 0; }
|
||||
@media (max-width:760px) { .tier-grid { grid-template-columns:1fr; } }
|
||||
.tier-card {
|
||||
@@ -72,147 +73,160 @@
|
||||
<body>
|
||||
|
||||
<div class="topnav">
|
||||
<a href="index.html" class="brand"><img src="assets/keysat-mark.svg" alt=""><span>Keysat</span></a>
|
||||
<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>
|
||||
<nav>
|
||||
<a href="install.html">Install</a>
|
||||
<a href="integrate.html">Integrate</a>
|
||||
<a href="wire-format.html">Wire format</a>
|
||||
<a href="operate.html">Operate</a>
|
||||
<a href="pricing.html" aria-current="page">Pricing</a>
|
||||
<a href="https://keysat.xyz">Marketing</a>
|
||||
</nav>
|
||||
</div>
|
||||
|
||||
<div class="layout">
|
||||
<aside class="side">
|
||||
<a href="#overview">Overview</a>
|
||||
<a href="#tiers">The three tiers</a>
|
||||
<a href="#what-counts">What the caps count</a>
|
||||
<a href="#changing-tiers">Switching tiers</a>
|
||||
<a href="#unlicensed">Running unlicensed</a>
|
||||
<a href="#future">What's coming</a>
|
||||
<div class="group">
|
||||
<div class="glabel">Get started</div>
|
||||
<a href="index.html">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#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" class="active">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="main">
|
||||
<main class="prose">
|
||||
<div class="crumb">Project · Pricing</div>
|
||||
<h1 id="overview">Pricing.</h1>
|
||||
<p class="lead">Keysat dogfoods its own licensing. The Keysat daemon is itself licensed by a Keysat instance running at <a href="https://licensing.keysat.xyz">licensing.keysat.xyz</a>. The same primitive operators use to gate features in their own software gates a few Keysat features behind paid tiers. The <strong>free tier is genuinely useful</strong>: most hobbyist operators will never need to upgrade.</p>
|
||||
|
||||
<h1 id="overview">Pricing</h1>
|
||||
<p class="lede">
|
||||
Keysat dogfoods its own licensing — the Keysat daemon is itself licensed by a Keysat
|
||||
instance running at <a href="https://licensing.keysat.xyz">licensing.keysat.xyz</a>.
|
||||
The same primitive operators use to gate features in their own software gates a few
|
||||
Keysat features behind paid tiers. The <strong>free tier is genuinely useful</strong> —
|
||||
most hobbyist operators will never need to upgrade.
|
||||
</p>
|
||||
<h2 id="tiers">The three tiers</h2>
|
||||
|
||||
<div id="tiers" class="tier-grid">
|
||||
<div class="tier-grid">
|
||||
|
||||
<div class="tier-card">
|
||||
<h3>Creator</h3>
|
||||
<div class="price">Free<span class="unit">forever</span></div>
|
||||
<div class="frequency">no payment required</div>
|
||||
<ul>
|
||||
<li>Up to 5 products</li>
|
||||
<li>Up to 5 policies per product</li>
|
||||
<li>Up to 10 active discount codes</li>
|
||||
<li>BTCPay payments (Bitcoin / Lightning)</li>
|
||||
<li>All four SDKs · full wire format</li>
|
||||
<li>Webhooks, audit log, recovery, analytics opt-in</li>
|
||||
<li>Self-host on Start9 (always)</li>
|
||||
</ul>
|
||||
<a class="cta secondary" href="https://licensing.keysat.xyz/buy/keysat?policy=creator">Get Creator</a>
|
||||
</div>
|
||||
|
||||
<div class="tier-card featured">
|
||||
<div class="badge">Most popular</div>
|
||||
<h3>Pro</h3>
|
||||
<div class="price">100,000<span class="unit">sats</span></div>
|
||||
<div class="frequency">per year (recurring)</div>
|
||||
<ul>
|
||||
<li>Unlimited products / policies / codes</li>
|
||||
<li>Recurring subscriptions: trials, grace, auto-renew</li>
|
||||
<li>Zaprite payments (expanded payment options including card payment capabilities)</li>
|
||||
<li>In-place tier upgrades (proration handled)</li>
|
||||
<li>Everything in Creator</li>
|
||||
</ul>
|
||||
<a class="cta" href="https://licensing.keysat.xyz/buy/keysat?policy=pro">Upgrade to Pro</a>
|
||||
</div>
|
||||
|
||||
<div class="tier-card">
|
||||
<h3>Patron</h3>
|
||||
<div class="price">250,000<span class="unit">sats</span></div>
|
||||
<div class="frequency">one-time, perpetual</div>
|
||||
<ul>
|
||||
<li>Everything in Pro</li>
|
||||
<li>Perpetual license: one-time, never renews</li>
|
||||
<li>Direct one-on-one support</li>
|
||||
<li>"Patron" badge in your admin UI</li>
|
||||
<li>Listed on the Patrons page at keysat.xyz</li>
|
||||
<li>Early access to release-candidate builds</li>
|
||||
</ul>
|
||||
<a class="cta secondary" href="https://licensing.keysat.xyz/buy/keysat?policy=patron">Become a Patron</a>
|
||||
</div>
|
||||
|
||||
<div class="tier-card">
|
||||
<h3>Creator</h3>
|
||||
<div class="price">21,000<span class="unit">sats</span></div>
|
||||
<div class="frequency">one-time, perpetual</div>
|
||||
<ul>
|
||||
<li>Up to 5 products</li>
|
||||
<li>Up to 5 policies per product</li>
|
||||
<li>Up to 5 active discount codes</li>
|
||||
<li>BTCPay payments (Bitcoin / Lightning)</li>
|
||||
<li>One-time purchases</li>
|
||||
<li>Self-host on Start9 (always)</li>
|
||||
<li>Distributed via free codes — ask</li>
|
||||
</ul>
|
||||
<a class="cta secondary" href="https://licensing.keysat.xyz/buy/keysat?policy=creator">Get Creator</a>
|
||||
</div>
|
||||
|
||||
<div class="tier-card featured">
|
||||
<div class="badge">Most popular</div>
|
||||
<h3>Pro</h3>
|
||||
<div class="price">250,000<span class="unit">sats</span></div>
|
||||
<div class="frequency">per year</div>
|
||||
<ul>
|
||||
<li>Unlimited products / policies / codes</li>
|
||||
<li>Recurring subscriptions <em>(when shipped, v0.3)</em></li>
|
||||
<li>Zaprite payments — accept BTC + cards <em>(when shipped, v0.3)</em></li>
|
||||
<li>Multi-operator admin <em>(when shipped)</em></li>
|
||||
<li>Everything in Creator</li>
|
||||
</ul>
|
||||
<a class="cta" href="https://licensing.keysat.xyz/buy/keysat?policy=pro">Upgrade to Pro</a>
|
||||
<div class="note">
|
||||
<strong>Prices shown are a snapshot.</strong> The canonical source is the live
|
||||
tier cards at <a href="https://keysat.xyz#tiers">keysat.xyz</a> (rendered
|
||||
dynamically from the master Keysat instance) and
|
||||
<a href="https://licensing.keysat.xyz/buy/keysat">licensing.keysat.xyz/buy/keysat</a>.
|
||||
Launch-special discounts (when active) show on those pages with a "LAUNCH
|
||||
SPECIAL" ribbon and the discount auto-applied; they're not represented here.
|
||||
</div>
|
||||
|
||||
<div class="tier-card">
|
||||
<h3>Patron</h3>
|
||||
<div class="price">500,000<span class="unit">sats</span></div>
|
||||
<div class="frequency">per year</div>
|
||||
<ul>
|
||||
<li>Same features as Pro</li>
|
||||
<li>"Patron" badge in your admin UI</li>
|
||||
<li>Funds Keysat development</li>
|
||||
<li>Honest upsell — no fake feature gate</li>
|
||||
</ul>
|
||||
<a class="cta secondary" href="https://licensing.keysat.xyz/buy/keysat?policy=patron">Become a Patron</a>
|
||||
<div class="note">
|
||||
<strong>What's gated.</strong> Capacity caps (products / policies-per-product /
|
||||
active discount codes) are enforced at create-time on the Creator tier. Pro
|
||||
unlocks the <code>recurring_billing</code> entitlement (auto-renewing
|
||||
subscriptions) and the <code>zaprite_payments</code> entitlement
|
||||
(expanded payment options including card payment capabilities).
|
||||
Patron differs from Pro in that it is a perpetual license (never
|
||||
expires or renews), plus direct one-on-one support. It's not a feature
|
||||
gate, it's a different ownership model.
|
||||
</div>
|
||||
|
||||
</div>
|
||||
<h2 id="what-counts">What the caps count</h2>
|
||||
<p>
|
||||
All caps fire at <strong>create-time only</strong>. Once you're under the cap,
|
||||
you're never retroactively kicked off. A Creator-tier operator who currently
|
||||
has 5 products keeps all 5 if you ever lower the caps in the future. The cap
|
||||
just stops them from creating a 6th.
|
||||
</p>
|
||||
<ul>
|
||||
<li><strong>Products</strong>: counts every product row in the database. Free up a slot by deleting products you no longer offer (the admin UI exposes delete; there's no "soft-disable" affordance for products).</li>
|
||||
<li><strong>Policies per product</strong>: counts policies on a single product, regardless of public/active state.</li>
|
||||
<li><strong>Active discount codes</strong>: counts only <code>active=true</code> codes. Disable old codes to free up slots without deleting them. Disabled codes don't function but stay in the audit trail.</li>
|
||||
</ul>
|
||||
|
||||
<div class="note">
|
||||
<strong>Note on what's gated.</strong> Today the only enforced gates are the
|
||||
capacity caps — number of products, policies, and active discount codes. Pro
|
||||
will gate the new payment-provider features (recurring billing, Zaprite card
|
||||
payments) when those ship in v0.3. Patron is functionally identical to Pro —
|
||||
its tier exists for operators who want to fund development beyond what Pro
|
||||
needs to stay in the green.
|
||||
</div>
|
||||
<h2 id="changing-tiers">Switching tiers</h2>
|
||||
<p>
|
||||
Buy a higher-tier license at <a href="https://licensing.keysat.xyz/buy/keysat">licensing.keysat.xyz/buy/keysat</a>,
|
||||
then activate it via StartOS → Keysat → Actions → <em>Activate Keysat license</em>.
|
||||
The daemon picks up the new entitlements on next request. No restart needed.
|
||||
The persistent banner in your admin sidebar always shows your current tier
|
||||
and the next-tier CTA.
|
||||
</p>
|
||||
<p>
|
||||
<strong>Downgrading</strong>: drop your license file (or replace with a lower
|
||||
tier). Existing rows stay; new ones are subject to the new caps. No data loss.
|
||||
</p>
|
||||
|
||||
<h2 id="what-counts">What the caps count</h2>
|
||||
<p>
|
||||
All caps fire at <strong>create-time only</strong>. Once you're under the cap,
|
||||
you're never retroactively kicked off. A Creator-tier operator who currently
|
||||
has 5 products keeps all 5 if you ever lower the caps in the future. The cap
|
||||
just stops them from creating a 6th.
|
||||
</p>
|
||||
<ul>
|
||||
<li><strong>Products</strong>: counts every product row (active + inactive). Operators don't get to evade the cap by toggling old rows inactive.</li>
|
||||
<li><strong>Policies per product</strong>: counts policies on a single product, regardless of public/active state.</li>
|
||||
<li><strong>Active discount codes</strong>: counts only <code>active=true</code> codes. Disable old codes to free up slots without deleting them — disabled codes don't function but stay in the audit trail.</li>
|
||||
</ul>
|
||||
|
||||
<h2 id="changing-tiers">Switching tiers</h2>
|
||||
<p>
|
||||
Buy a higher-tier license at <a href="https://licensing.keysat.xyz/buy/keysat">licensing.keysat.xyz/buy/keysat</a>,
|
||||
then activate it via StartOS → Keysat → Actions → <em>Activate Keysat license</em>.
|
||||
The daemon picks up the new entitlements on next request — no restart needed.
|
||||
The persistent banner in your admin sidebar always shows your current tier
|
||||
and the next-tier CTA.
|
||||
</p>
|
||||
<p>
|
||||
<strong>Downgrading</strong>: drop your license file (or replace with a lower
|
||||
tier). Existing rows stay; new ones are subject to the new caps. No data loss.
|
||||
</p>
|
||||
|
||||
<h2 id="unlicensed">Running unlicensed</h2>
|
||||
<p>
|
||||
Keysat works without any license at all — you'll see "Unlicensed" in the
|
||||
sidebar and get the same caps as a Creator-tier operator (5/5/5). The
|
||||
license exists primarily so operators get a real "I bought it" experience
|
||||
and so we can offer the upgrade path to Pro. Hobbyists can run Keysat
|
||||
indefinitely without paying us a sat.
|
||||
</p>
|
||||
|
||||
<h2 id="future">What's coming</h2>
|
||||
<p>
|
||||
Two big v0.3 features will be Pro-only when they ship:
|
||||
</p>
|
||||
<ul>
|
||||
<li><strong>Recurring subscriptions</strong> — auto-renewal, customer-managed cancellation.</li>
|
||||
<li><strong>Zaprite payments</strong> — accept Bitcoin <em>and</em> credit cards. Massively expands your addressable buyers.</li>
|
||||
</ul>
|
||||
<p>
|
||||
Both will gate on the <code>recurring_billing</code> and <code>card_payments</code> entitlements
|
||||
respectively. Free-tier operators will see a "Pro feature" banner and a one-click
|
||||
upgrade flow when they try to use these.
|
||||
</p>
|
||||
<h2 id="unlicensed">Running unlicensed</h2>
|
||||
<p>
|
||||
Keysat works without any license at all. You'll see "Unlicensed" in the
|
||||
sidebar and get the same caps as a Creator-tier operator
|
||||
(5 products / 5 policies per product / 10 active discount codes). The
|
||||
Creator tier is free either way; the self-license flow exists primarily so
|
||||
operators get a real "I bought it" experience for the paid tiers and so we
|
||||
can offer the upgrade path to Pro. Hobbyists can run Keysat indefinitely
|
||||
without paying us a sat.
|
||||
</p>
|
||||
|
||||
</main>
|
||||
</div>
|
||||
|
||||
<script src="docs.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
+62
-74
@@ -3,22 +3,15 @@
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>Keysat Docs — Wire format reference</title>
|
||||
<title>Keysat Docs: Wire format reference</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="index.html" class="brand"><img src="assets/keysat-mark.svg" alt=""><span>Keysat</span></a>
|
||||
<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>
|
||||
<nav>
|
||||
<a href="install.html">Install</a>
|
||||
<a href="integrate.html">Integrate</a>
|
||||
<a href="wire-format.html" class="active">Wire format</a>
|
||||
<a href="operate.html">Operate</a>
|
||||
<a href="https://keysat.xyz">Marketing</a>
|
||||
</nav>
|
||||
</div>
|
||||
|
||||
<div class="layout">
|
||||
@@ -28,6 +21,7 @@
|
||||
<a href="index.html">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>
|
||||
@@ -39,8 +33,11 @@
|
||||
<div class="group">
|
||||
<div class="glabel">Reference</div>
|
||||
<a href="wire-format.html" class="active">Wire format</a>
|
||||
<a href="integrate.html#api">Admin API</a>
|
||||
<a href="integrate.html#sdks">SDKs</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>
|
||||
@@ -56,68 +53,59 @@
|
||||
<p class="lead">The bytes-over-the-wire spec for a Keysat license. Stable across SDKs and across language ports. About 90 lines of pseudocode to implement in a new language.</p>
|
||||
|
||||
<h2 id="overview">Overview</h2>
|
||||
<p>A Keysat license key looks like this on a receipt:</p>
|
||||
<p>A Keysat license key on a receipt looks like this:</p>
|
||||
|
||||
<pre class="code">KS-9F2A-7C41-XK22-6D8E-LM77-PQ91</pre>
|
||||
<pre class="code">LIC1-<base32 payload>-<base32 signature></pre>
|
||||
|
||||
<p>Strip the <code>KS-</code> prefix and the dashes, and you have a Crockford base32-encoded blob. Base32-decode that blob, and you get the binary <em>license envelope</em>: a fixed-layout struct followed by an Ed25519 signature.</p>
|
||||
<p>Three parts, separated by single dashes:</p>
|
||||
<ul>
|
||||
<li><code>LIC1</code>: literal envelope tag. Future format revisions get a new tag (<code>LIC2</code> etc.). Parsers MUST reject unknown tags.</li>
|
||||
<li><code><base32 payload></code>: the signed payload bytes, RFC 4648 base32 without padding (case-insensitive on decode). Variable length depending on payload version and number of entitlements.</li>
|
||||
<li><code><base32 signature></code>: the 64-byte Ed25519 signature over the <em>raw payload bytes</em>, base32-encoded the same way.</li>
|
||||
</ul>
|
||||
<p>To verify: split on <code>-</code>, validate the tag is <code>LIC1</code>, base32-decode both chunks (case-fold to upper), parse the payload, and verify the signature bytes against the raw payload bytes using the issuer’s Ed25519 public key.</p>
|
||||
|
||||
<h2 id="layout">Binary layout</h2>
|
||||
<p>All multi-byte integers are big-endian.</p>
|
||||
<h2 id="versions">Two payload versions</h2>
|
||||
<p>Keysat ships two payload versions today. v2 is the current default that the daemon issues; v1 verifiers stay in the SDKs forever so legacy keys keep verifying.</p>
|
||||
|
||||
<h3>v1 (legacy, fixed 74 bytes)</h3>
|
||||
<p>Issued by the very early daemon builds. No expiry, no entitlements. Perpetual only, fingerprint binding optional. Still accepted on parse so old customer keys don’t break.</p>
|
||||
<table class="t">
|
||||
<thead><tr><th>Offset</th><th>Length</th><th>Field</th><th>Notes</th></tr></thead>
|
||||
<tbody>
|
||||
<tr><td><code>0</code></td><td>4</td><td>Magic</td><td>ASCII <code>KSAT</code> (0x4B 0x53 0x41 0x54).</td></tr>
|
||||
<tr><td><code>4</code></td><td>1</td><td>Version</td><td>Currently <code>0x01</code>. Decoders MUST reject unknown versions.</td></tr>
|
||||
<tr><td><code>5</code></td><td>1</td><td>Flags</td><td>Bit 0: <code>TRIAL</code>. Bit 1: <code>PERPETUAL</code>. Bits 2–7 reserved.</td></tr>
|
||||
<tr><td><code>6</code></td><td>16</td><td>License ID</td><td>UUIDv4 binary form.</td></tr>
|
||||
<tr><td><code>22</code></td><td>16</td><td>Issuer fingerprint</td><td>SHA-256 of the issuer public key, truncated to 16 bytes.</td></tr>
|
||||
<tr><td><code>38</code></td><td>8</td><td>Issued-at</td><td>Unix seconds, signed.</td></tr>
|
||||
<tr><td><code>46</code></td><td>8</td><td>Expires-at</td><td>Unix seconds, signed. <code>0</code> if <code>PERPETUAL</code> flag is set.</td></tr>
|
||||
<tr><td><code>54</code></td><td>2</td><td>Seats</td><td>Max machines. <code>0</code> = unlimited.</td></tr>
|
||||
<tr><td><code>56</code></td><td>2</td><td>Payload length</td><td>Length <code>L</code> of the variable-size payload that follows.</td></tr>
|
||||
<tr><td><code>58</code></td><td><code>L</code></td><td>Payload</td><td>UTF-8 JSON: <code>{ "product": "...", "policy": "...", "entitlements": [...] }</code>.</td></tr>
|
||||
<tr><td><code>58 + L</code></td><td>64</td><td>Signature</td><td>Ed25519 signature over bytes <code>0 .. (58 + L)</code>.</td></tr>
|
||||
<tr><td><code>0</code></td><td>1</td><td>version</td><td><code>0x01</code></td></tr>
|
||||
<tr><td><code>1</code></td><td>1</td><td>flags</td><td>Bit 0: fingerprint-bound. Other bits reserved.</td></tr>
|
||||
<tr><td><code>2</code></td><td>16</td><td>product_id</td><td>UUID, big-endian bytes.</td></tr>
|
||||
<tr><td><code>18</code></td><td>16</td><td>license_id</td><td>UUID, big-endian bytes.</td></tr>
|
||||
<tr><td><code>34</code></td><td>8</td><td>issued_at</td><td>Unix seconds, u64 big-endian.</td></tr>
|
||||
<tr><td><code>42</code></td><td>32</td><td>fingerprint_hash</td><td>SHA-256 of the machine fingerprint; all zeros if not bound.</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h2 id="encoding">Crockford base32</h2>
|
||||
<p>Keysat uses <a href="https://www.crockford.com/base32.html">Crockford’s base32 alphabet</a> (<code>0123456789ABCDEFGHJKMNPQRSTVWXYZ</code>) without checksum, without padding, and case-insensitive on decode.</p>
|
||||
|
||||
<p>The reason for Crockford over standard base32: human-friendly. <code>I</code>, <code>L</code>, <code>O</code>, <code>U</code> are excluded from the alphabet to avoid ambiguity when typing keys off a printed receipt.</p>
|
||||
|
||||
<h2 id="grouping">Dash grouping & prefix</h2>
|
||||
<p>For display, keys are upper-cased, then grouped into 4-character chunks separated by dashes, and prefixed with <code>KS-</code>:</p>
|
||||
|
||||
<pre class="code"><span class="c">// raw base32, length depends on payload size</span>
|
||||
9F2A7C41XK226D8ELM77PQ91RR54VV01
|
||||
|
||||
<span class="c">// grouped + prefixed for display</span>
|
||||
KS-9F2A-7C41-XK22-6D8E-LM77-PQ91-RR54-VV01</pre>
|
||||
|
||||
<p>Decoders MUST strip the <code>KS-</code> prefix (case-insensitive), strip whitespace and dashes, and case-fold to upper before base32-decoding.</p>
|
||||
<h3>v2 (current default, variable length)</h3>
|
||||
<p>83-byte fixed head + variable-length entitlements table. v2 adds expiry, trial flag, and entitlements, all signed so offline verifiers can gate features without contacting the server (a stripped entitlement or pushed-back expiry would have to match a valid signature, which the attacker can’t produce).</p>
|
||||
<table class="t">
|
||||
<thead><tr><th>Offset</th><th>Length</th><th>Field</th><th>Notes</th></tr></thead>
|
||||
<tbody>
|
||||
<tr><td><code>0</code></td><td>1</td><td>version</td><td><code>0x02</code></td></tr>
|
||||
<tr><td><code>1</code></td><td>1</td><td>flags</td><td>Bit 0: fingerprint-bound. Bit 1: trial (best-effort hint for clients).</td></tr>
|
||||
<tr><td><code>2</code></td><td>16</td><td>product_id</td><td>UUID, big-endian bytes.</td></tr>
|
||||
<tr><td><code>18</code></td><td>16</td><td>license_id</td><td>UUID, big-endian bytes.</td></tr>
|
||||
<tr><td><code>34</code></td><td>8</td><td>issued_at</td><td>Unix seconds, u64 big-endian.</td></tr>
|
||||
<tr><td><code>42</code></td><td>8</td><td>expires_at</td><td>Unix seconds, u64 big-endian. <code>0</code> means perpetual.</td></tr>
|
||||
<tr><td><code>50</code></td><td>32</td><td>fingerprint_hash</td><td>SHA-256 of the machine fingerprint; all zeros if not bound.</td></tr>
|
||||
<tr><td><code>82</code></td><td>1</td><td>entitlements_count</td><td><code>N</code>, 0–255.</td></tr>
|
||||
<tr><td><code>83..</code></td><td>variable</td><td>entitlements</td><td><code>N</code> entries, each <code><len: u8><ascii bytes></code>. Each entitlement string is ≤255 bytes.</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h2 id="signature">Signature</h2>
|
||||
<p>The signature covers the entire envelope from offset <code>0</code> through the end of the payload — that is, all bytes <em>before</em> the 64-byte signature itself.</p>
|
||||
<p>The signature is computed over the <strong>raw payload bytes</strong>: the binary head plus any entitlements table, without the version tag, without base32 encoding, without dashes. The two base32 chunks in the wire format are encoded <em>independently</em>; concatenating them and base32-decoding the whole would be wrong.</p>
|
||||
<p>Verify with the issuer’s Ed25519 public key (PEM-encoded, SubjectPublicKeyInfo). The SDKs ship the public key bundled in your app at build time; they don’t fetch it at runtime. (The whole point of offline verification is that a network-level attacker can’t hand your software a different key.)</p>
|
||||
|
||||
<p>Verify with the issuer’s Ed25519 public key. The fingerprint at offset 22 lets the verifier confirm that the key it has matches the key the license was signed with: SHA-256 the public key bytes, truncate to 16 bytes, compare. If it doesn’t match, the verifier MUST reject before attempting signature check — this gives a clear "wrong issuer" error rather than a generic "bad signature".</p>
|
||||
|
||||
<h2 id="example">Worked example</h2>
|
||||
<p>Test vector for the Python SDK’s cross-check tests (issuer fingerprint <code>0xfeed face cafe babe...</code>, single-seat perpetual license):</p>
|
||||
|
||||
<pre class="code"><span class="c"># Hex dump of the binary envelope</span>
|
||||
00000000 4B 53 41 54 01 02 9F 2A 7C 41 XK 22 6D 8E LM 77 <span class="c">|KSAT...*|A.."m..w|</span>
|
||||
00000010 PQ 91 RR 54 VV 01 FE ED FA CE CA FE BA BE 00 00 <span class="c">|...T....|........|</span>
|
||||
00000020 00 00 00 00 65 4F 12 34 00 00 00 00 00 00 00 00 <span class="c">|....eO.4|........|</span>
|
||||
00000030 00 01 00 24 7B 22 70 72 6F 64 75 63 74 22 3A 22 <span class="c">|...${"product":"|</span>
|
||||
00000040 73 75 6E 64 69 61 6C 22 2C 22 70 6F 6C 69 63 79 <span class="c">|sundial","policy|</span>
|
||||
00000050 22 3A 22 64 65 66 61 75 6C 74 22 7D ...sig... <span class="c">|":"default"}.....|</span>
|
||||
|
||||
<span class="c"># As displayed</span>
|
||||
KS-9F2A-7C41-XK22-6D8E-LM77-PQ91-…</pre>
|
||||
|
||||
<p>The full vector lives in <code>licensing-client-python/tests/fixtures/canonical.json</code> and is what every official SDK is tested against.</p>
|
||||
<h2 id="encoding">Base32 alphabet</h2>
|
||||
<p>Standard RFC 4648 base32 (alphabet <code>A–Z, 2–7</code>), no padding, case-insensitive on decode. The daemon emits uppercase. Decoders MUST strip whitespace and case-fold to upper before decoding.</p>
|
||||
<p>Why not Crockford / hex / base58: standard base32 has wide library support, encodes 5 bytes per 8 characters (slightly tighter than hex), is case-insensitive for type-on-receipt scenarios, and avoids the I/O/0/1 ambiguity of base58.</p>
|
||||
|
||||
<h2 id="public-key">Issuer public key format</h2>
|
||||
<p>Public keys are exchanged in PEM format, SubjectPublicKeyInfo encoded:</p>
|
||||
@@ -138,33 +126,32 @@ MCowBQYDK2VwAyEAmz7q8r4t1v…h3k2pXq9wL
|
||||
<p>The wire format is small enough to port in an afternoon. The order is:</p>
|
||||
|
||||
<ol>
|
||||
<li>Copy the test vectors from <a href="https://github.com/keysat-xyz/licensing-client-python/blob/main/tests/fixtures/canonical.json">licensing-client-python/tests/fixtures/canonical.json</a>.</li>
|
||||
<li>Implement Crockford base32 decode (~30 lines).</li>
|
||||
<li>Implement the binary unmarshal (~40 lines, mostly offset arithmetic).</li>
|
||||
<li>Wire it up to your language’s Ed25519 verifier from a vetted crypto library.</li>
|
||||
<li>Run the cross-check tests — if they pass, you’re wire-compatible.</li>
|
||||
<li>Pull the canonical cross-check vectors from the daemon repo at <a href="https://github.com/keysat-xyz/keysat/tree/main/licensing-service/tests/crosscheck"><code>licensing-service/tests/crosscheck/</code></a>. Vectors cover v1 legacy, v2 trial-with-entitlements, and v2 perpetual-unbound fixtures.</li>
|
||||
<li>Implement RFC 4648 base32 decode (most languages have this in stdlib).</li>
|
||||
<li>Implement the binary unmarshal for both v1 and v2 payloads (~80 lines total, mostly big-endian integer reads).</li>
|
||||
<li>Wire it up to your language’s Ed25519 verifier from a vetted crypto library (libsodium, ring, ed25519-dalek, the Node/Python stdlib, etc.).</li>
|
||||
<li>Run the cross-check tests. If all three vector cases pass byte-for-byte, you’re wire-compatible.</li>
|
||||
</ol>
|
||||
|
||||
<p>See <a href="https://github.com/keysat-xyz/keysat/blob/main/PORTING_SDK_TO_NEW_LANGUAGES.md">PORTING_SDK_TO_NEW_LANGUAGES.md</a> in the repo for the full contributor guide.</p>
|
||||
<p>The four official SDKs (Rust, TypeScript, Python, Go) all sit on top of these same fixtures and the daemon’s test suite asserts each implementation round-trips them identically before a release ships.</p>
|
||||
|
||||
<h2 id="versioning">Versioning policy</h2>
|
||||
<p>The version byte at offset 4 is a hard gate. Decoders MUST reject any version they don’t implement. We commit to:</p>
|
||||
<p>The version byte at payload offset <code>0</code> is a hard gate. Decoders MUST reject any version they don’t implement (no graceful skip-over). We commit to:</p>
|
||||
|
||||
<ul>
|
||||
<li>Never silently changing the v1 layout. Any change ⇒ new version byte.</li>
|
||||
<li>Maintaining v1 verifier support indefinitely — even if v2 ships, your existing customer keys stay verifiable.</li>
|
||||
<li>Publishing test vectors for every new version under <code>tests/fixtures/</code> in the canonical SDK.</li>
|
||||
<li>Never silently changing an existing layout. Any field-shape change ⇒ new version byte.</li>
|
||||
<li>Maintaining v1 + v2 verifier support indefinitely. If v3 ever ships, your existing customer keys still verify against the daemon and the SDKs they shipped with.</li>
|
||||
<li>The wire-envelope tag (<code>LIC1-…</code>) bumps only on a breaking envelope change. New payload versions live inside the same envelope tag as long as the split-on-dash structure stays the same.</li>
|
||||
<li>Publishing test vectors for every payload version under <code>tests/crosscheck/</code> in the daemon repo. All five implementations (daemon, Rust SDK, TypeScript SDK, Python SDK, Go SDK) are required to round-trip the same vectors byte-for-byte before a release ships.</li>
|
||||
</ul>
|
||||
</main>
|
||||
|
||||
<aside class="toc">
|
||||
<div class="label">On this page</div>
|
||||
<a href="#overview">Overview</a>
|
||||
<a href="#layout">Binary layout</a>
|
||||
<a href="#encoding">Crockford base32</a>
|
||||
<a href="#grouping">Dash grouping</a>
|
||||
<a href="#versions">Payload versions</a>
|
||||
<a href="#signature">Signature</a>
|
||||
<a href="#example">Worked example</a>
|
||||
<a href="#encoding">Base32 alphabet</a>
|
||||
<a href="#public-key">Public key format</a>
|
||||
<a href="#porting">Porting</a>
|
||||
<a href="#versioning">Versioning policy</a>
|
||||
@@ -173,5 +160,6 @@ MCowBQYDK2VwAyEAmz7q8r4t1v…h3k2pXq9wL
|
||||
|
||||
<script src="https://unpkg.com/lucide@latest"></script>
|
||||
<script>lucide.createIcons();</script>
|
||||
<script src="docs.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
Reference in New Issue
Block a user