Integrate the SDK.

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.

Prerequisites

Before you start, you should have:

• A Keysat installation running on your Start9; see Install & setup.
• BTCPay Server connected to Keysat; ditto.
• At least one product defined in the admin UI.

Pick an SDK

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.

# npm
npm install @keysat/licensing-client

# pnpm
pnpm add @keysat/licensing-client

# Cargo.toml
[dependencies]
keysat-licensing-client = "0.3"

# pip
pip install keysat-licensing-client

# or with poetry
poetry add keysat-licensing-client

// go.mod
go get github.com/keysat-xyz/keysat-client-go

// stdlib only: no third-party Go dependencies

If your language isn’t covered, see Wire format. The format is small and porting takes about an afternoon.

Step 1: Embed your public key

In the admin UI, open Overview and copy the issuer public key from the "Embed your public key" card. (Or fetch it from GET /v1/issuer/public-key.) Paste it into your application’s source code as a compile-time constant.

const ISSUER_PEM = `-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAmz7q8r4t1v…h3k2pXq9wL
-----END PUBLIC KEY-----`;

const ISSUER_PEM: &str = "-----BEGIN PUBLIC KEY-----\n\
MCowBQYDK2VwAyEAmz7q8r4t1v…h3k2pXq9wL\n\
-----END PUBLIC KEY-----";

ISSUER_PEM = b"""-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAmz7q8r4t1v…h3k2pXq9wL
-----END PUBLIC KEY-----"""

Step 2: Verify a license at startup

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. In a server-side app the key arrives per request instead: read it from a header you define (for example X-License-Key) or the session, then verify it the same way.

import { Verifier, PublicKey } from '@keysat/licensing-client';

const verifier = new Verifier(
  PublicKey.fromPem(ISSUER_PEM)
);

// verify() returns the verified license, or THROWS if the key is missing,
// malformed, forged, or signed by someone else. Catch it (see step 3).
const license = verifier.verify(licenseKeyFromUser);

// What you do next is up to YOUR business model. The verified payload
// carries the entitlements baked in at issue time.
app.licensed = true;
app.entitlements = license.payload.entitlements; // string[]

use licensing_client::{Verifier, PublicKeyPem};

let pk = PublicKeyPem::from_str(ISSUER_PEM)?;
let verifier = Verifier::new(pk);

// verify() returns Ok(VerifyOk) or Err on a bad key (see step 3).
let license = verifier.verify(&license_key)?;

app.licensed = true;
app.entitlements = license.payload.entitlements;

from keysat_licensing_client import Verifier, PublicKey

verifier = Verifier(PublicKey.from_pem(ISSUER_PEM))

# verify() returns the verified license, or RAISES on a bad key (see step 3).
license = verifier.verify(license_key_from_user)

app.licensed = True
app.entitlements = license.payload.entitlements

On success, verify() returns a VerifyOk result. There is no valid boolean: an invalid key throws (TS / Python) or returns Err (Rust). See step 3. Field names are camelCase in TS/JS and snake_case in Rust/Python.

Step 3: Handle errors gracefully

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:

import { LicensingError } from '@keysat/licensing-client';

try {
  const license = verifier.verify(licenseKey); // throws if not valid
  grantAccess(license);
} catch (e) {
  // Every failure is a LicensingError with a machine-readable .code:
  // 'bad_signature' (tampered / forged), 'bad_format' or 'bad_encoding'
  // (garbled input), 'bad_version', 'expired' (only from verifyWithTime).
  if (e instanceof LicensingError && e.code === 'bad_signature') showTamperWarning();
  else if (e instanceof LicensingError) showInputError();
  else showGenericError(e);
}

use licensing_client::Error;

match verifier.verify(&license_key) {
    Ok(license) => grant_access(&license),
    Err(Error::BadSignature) => show_tamper_warning(),
    Err(Error::BadFormat(_) | Error::BadEncoding(_)) => show_input_error(),
    Err(e) => show_generic_error(e),
}

from keysat_licensing_client import LicensingError

try:
    license = verifier.verify(license_key)  # raises if not valid
    grant_access(license)
except LicensingError as e:
    if e.kind == "bad_signature":
        show_tamper_warning()
    elif e.kind.startswith("bad_"):
        show_input_error()
    else:
        show_generic_error(e)

Renewals & revocation

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.

If you need revocation, ship a thin online check that re-validates the key on a cadence (e.g. once a week) against your Keysat’s POST /v1/validate. A revoked license returns ok: false with reason: "revoked":

// Optional. Run on a cadence, ignore network errors.
async function checkRevocation(licenseKey: string) {
  const r = await fetch('https://your-keysat.example/v1/validate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ key: licenseKey }),
  });
  if (r.ok) {
    const j = await r.json();
    if (!j.ok && j.reason === 'revoked') disableApp();
  }
}

// Optional. Run on a cadence, ignore network errors.
async fn check_revocation(license_key: &str) {
    let body = serde_json::json!({ "key": license_key });
    if let Ok(r) = reqwest::Client::new()
        .post("https://your-keysat.example/v1/validate")
        .json(&body)
        .send()
        .await
    {
        if let Ok(j) = r.json::<ValidateResp>().await {
            if !j.ok && j.reason.as_deref() == Some("revoked") { disable_app(); }
        }
    }
}

# Optional. Run on a cadence, ignore network errors.
def check_revocation(license_key):
    try:
        r = requests.post("https://your-keysat.example/v1/validate", json={"key": license_key}, timeout=5)
        j = r.json()
        if not j["ok"] and j.get("reason") == "revoked":
            disable_app()
    except Exception:
        pass

Admin API

The admin UI is a thin shell over a small JSON API. Bearer-auth all requests with your admin API key.

Full schemas for each endpoint live in Wire format & API reference.