The Bouncer's Playbook

Overview

There are two ways to use KeyBouncer. Most apps use both.

Your client app always talks to KeyBouncer directly with a publishable key, there is no proxy or server for you to host.

Key types: publishable vs secret

KeyBouncer has two API key classes. Never ship a secret key in a client, anyone could extract it and revoke or read your customers. Embed a publishable key instead; it is hard-limited (server-side) to the validate set.

Create keys in Dashboard → API Keys. Choose a class; for secret keys, pick the operation scopes it needs (leave all unselected for a full-access key):

# Client app, publishable key, validate only
curl -X POST https://your-domain.com/api/v1/licenses/validate \
  -H "Authorization: Bearer kb_pub_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"license_key": "XXXX-XXXX-XXXX-XXXX"}'

# Your server, secret key, full management
curl -X POST https://your-domain.com/api/v1/licenses \
  -H "Authorization: Bearer kb_live_xxx" \
  -H "Idempotency-Key: order-1234" \
  -H "Content-Type: application/json" \
  -d '{"application_id": "app_123", "email": "buyer@example.com"}'

Quickstart: sell + license in ~10 minutes

1. 1

   Create an application

   Dashboard → Applications → New. This is your product; it gets an RSA keypair for offline licenses automatically.

2. 2

   Connect Stripe

   Dashboard → Payments → Connect Stripe. Complete Stripe-hosted onboarding. When "Charges Enabled" shows green you can sell.

3. 3

   Create a plan

   Dashboard → Plans → New Plan. Pick the app, set a price and device count. KeyBouncer creates the Stripe product/price on your connected account.

4. 4

   Brand it (optional)

   Plans → Appearance: set the page title, sub-description, theme (dark/light), and brand colors for your storefront and emails.

5. 5

   Grab keys

   Dashboard → API Keys: make a publishable key for your app, and a secret key if you will use the management API.

6. 6

   Ship the link

   Plans → Storefront links: copy your buy link (/a/{slug}) and recover link. Put the buy link on your site or in-app "Buy" button.

On purchase the buyer is charged on your Stripe account, gets the license by email, and sees it on the success page. You can then validate it from your app (next sections).

Selling with Stripe (Connect)

KeyBouncer uses Stripe Connect (Standard) with hosted onboarding. Buyers are charged directly on your own Stripe account (direct charges, no platform fee), KeyBouncer never holds your money, and you are the merchant of record.

Bundles (multi-app licenses)

A Bundle groups several applications so a single license key validates across all of them, an “all-access pass.” Individual per-app licenses keep working unchanged; an app can be sold both ways.

For your client app, nothing changes: validate with the app's publishable key. A bundle key is accepted because the app is a member, and the response carries that app's entitlements:

# From App A (a bundle member), same call as always
curl -X POST https://your-domain.com/api/v1/licenses/validate \
  -H "Authorization: Bearer kb_pub_live_APP_A_KEY" \
  -d '{"license_key": "BUNDLE-KEY", "product_id": "app_A_id"}'
# -> valid; features resolved for App A. A non-member app gets PRODUCT_MISMATCH.

Selling through Plans is optional, you can mint bundle licenses from your own backend (your own payments), exactly like single-app licenses, by passing bundle_id instead of application_id:

curl -X POST https://your-domain.com/api/v1/licenses \
  -H "Authorization: Bearer kb_live_xxx" \
  -H "Idempotency-Key: order-1234" \
  -d '{"bundle_id": "bun_123", "email": "buyer@example.com"}'
# (use an account-level secret key, not an app-scoped one)

Offline: a bundle .lic is signed by the bundle's key and carries an applications[] array. Member apps fetch the bundle key from /api/v1/bundles/{id}/public-key and check their own app id is in the list.

Hosted pages & branding

KeyBouncer hosts a small, branded page set per app at /a/{slug}. You build no front-end.

Set branding in Plans → Appearance. It applies to every hosted page and your transactional emails:

• Page title and sub-description
• Theme, dark (default) or light
• Primary & accent colors (buttons, accents, glow)
• Support email, website URL, download URL

Custom logos and custom domains are on the roadmap; for now pages live under your KeyBouncer domain.

Customers & license management API

Create and manage licenses from your own server with a secret key. Pass an Idempotency-Key header on creates so retries never duplicate. Customers are tracked by the email on each license; look them up with the list endpoint.

{
  "application_id": "app_123",   // exactly one of application_id OR bundle_id
  "bundle_id": "bndl_123",       // (bundle_id mints one key valid across the bundle)
  "email": "buyer@example.com",
  "name": "Jane Doe",
  "tier_id": "tier_pro",        // optional (applications only)
  "license_type": "PERPETUAL",  // PERPETUAL | SUBSCRIPTION | TRIAL
  "max_activations": 3,
  "expires_at": "2027-01-01T00:00:00Z", // optional
  "features": { "export": true },        // optional overrides
  "metadata": { "order": "1234" }        // optional
}

{
  "success": true,
  "data": {
    "id": "lic_abc",
    "key": "XXXX-XXXX-XXXX-XXXX",  // full key, shown once
    "key_prefix": "XXXX-XXX",
    "status": "ACTIVE",
    "type": "PERPETUAL",
    "max_activations": 3,
    "customer_email": "buyer@example.com",
    "source": "api"
  }
}

Query params: email, application_id, status, page

{
  "success": true,
  "data": [ { "id": "lic_abc", "key_prefix": "XXXX-XXX", "status": "ACTIVE", "customer_email": "buyer@example.com" } ],
  "pagination": { "page": 1, "pageSize": 50, "total": 1, "totalPages": 1 }
}

{
  "status": "ACTIVE",
  "expires_at": "2027-06-01T00:00:00Z",
  "max_activations": 5,
  "features": { "export": true }
}

{ "success": true, "data": { "id": "lic_abc", "status": "ACTIVE", "max_activations": 5 } }

// revoke / suspend / reactivate: empty body
// renew:
{ "expires_at": "2027-06-01T00:00:00Z" }

{ "success": true, "data": { "id": "lic_abc", "status": "REVOKED" } }

Validation API

The endpoints your app calls. A publishable key is allowed on all of these; a secret key needs licenses:validate (validate/check) or licenses:write (activate/deactivate).

{
  "license_key": "XXXX-XXXX-XXXX-XXXX",
  "hardware_id": "optional-device-id",
  "product_id": "optional-app-id"
}

{
  "valid": true,
  "license": {
    "type": "PERPETUAL",
    "status": "ACTIVE",
    "expires_at": null,
    "features": { "export": true },
    "tier": "Pro",
    "activations": 1,
    "max_activations": 3
  }
}

{
  "license_key": "XXXX-XXXX-XXXX-XXXX",
  "hardware_id": "device-unique-id",
  "device_name": "Jane's MacBook Pro",
  "device_metadata": { "os": "macOS", "arch": "arm64" }
}

{
  "activated": true,
  "license": { "status": "ACTIVE", "activations": 1, "max_activations": 3 },
  "activation": { "id": "...", "hardware_id": "...", "device_name": "..." },
  "activation_token": "kbact_...",   // keep this to deactivate later
  "offline_license": "<header>.<payload>.<signature>",
  "key_id": "a1b2c3d4e5f60718"
}

{
  "license_key": "XXXX-XXXX-XXXX-XXXX",
  "hardware_id": "device-unique-id",
  "activation_token": "kbact_..."   // required for publishable keys
}

{ "deactivated": true }

Query params: ?license_key=XXXX-XXXX&hardware_id=device-id

{ "valid": true, "status": "ACTIVE", "expires_at": null, "features": { "export": true } }

No body.

{ "application_id": "app_123", "public_key": "-----BEGIN PUBLIC KEY-----...", "key_id": "a1b2c3d4e5f60718", "algorithm": "RS256" }

{ "email": "buyer@example.com", "application_id": "app_123" }

{ "accepted": true }   // HTTP 202

Devices & activations

Each license has a device limit (max_activations). When a device activates, the response includes an opaque activation_token for that device. Store it locally.

Offline licenses

A successful activate returns a hardware-bound, RSA-signed .lic token in offline_license (on plans that include offline validation; you can also generate one from the dashboard). Verify it locally with the app public key, no network needed.

// decoded payload
{
  "version": 1,
  "keyId": "a1b2c3d4e5f60718",      // matches the public-key endpoint
  "licenseId": "lic_abc",
  "applicationId": "app_123",
  "hardwareId": "device-unique-id",  // null if not device-bound
  "tier": "Pro",
  "features": { "export": true },
  "licenseType": "PERPETUAL",
  "status": "ACTIVE",
  "maxActivations": 3,
  "expiresAt": "2027-01-01T00:00:00Z",
  "graceUntil": null,                // honored past expiry if set
  "issuedAt": "2026-06-26T12:00:00Z"
}

const crypto = require('crypto');

// The app's public key, fetch from /api/v1/applications/{id}/public-key and embed it.
const PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
...
-----END PUBLIC KEY-----`;

function verifyOfflineLicense(token, hardwareId) {
  const [header, payload, signature] = token.split('.');
  if (!header || !payload || !signature) return { valid: false, error: 'INVALID_FORMAT' };

  const ok = crypto.createVerify('RSA-SHA256')
    .update(`${header}.${payload}`)
    .verify(PUBLIC_KEY, signature, 'base64url');
  if (!ok) return { valid: false, error: 'INVALID_SIGNATURE' };

  const lic = JSON.parse(Buffer.from(payload, 'base64url').toString());

  const now = new Date();
  if (lic.expiresAt && new Date(lic.expiresAt) < now) {
    const graceOk = lic.graceUntil && new Date(lic.graceUntil) >= now;
    if (!graceOk) return { valid: false, error: 'LICENSE_EXPIRED' };
  }
  if (lic.hardwareId && lic.hardwareId !== hardwareId) {
    return { valid: false, error: 'HARDWARE_MISMATCH' };
  }
  return { valid: true, license: lic };
}

Webhooks

Subscribe in Dashboard → Webhooks to react in your own systems. Deliveries are signed and retried with backoff; logs and manual retry are in the dashboard.

Payloads carry keyPrefix only, never the full key. Fetch the full key with a secret key if you need it.

// POST to your endpoint
{
  "event": "LICENSE_CREATED",
  "data": { "license": { "id": "lic_abc", "keyPrefix": "XXXX-XXX", "status": "ACTIVE", "licenseType": "PERPETUAL", "application": "Quill", "customerEmail": "buyer@example.com" } },
  "timestamp": "2026-06-26T12:00:00.000Z"
}

Verify the signature. Sign {timestamp}.{raw body} with your endpoint secret (HMAC-SHA256) and compare to the header:

const crypto = require('crypto');

function verify(rawBody, headers, secret) {
  const signature = headers['x-keybouncer-signature'];
  const timestamp = headers['x-keybouncer-timestamp'];
  const expected = crypto.createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}
// Headers: X-KeyBouncer-Signature, X-KeyBouncer-Timestamp, X-KeyBouncer-Event, X-KeyBouncer-Retry

Desktop client integration

Recommended pattern: embed a publishable key, activate once (store the returned activation_token and offline_license), then verify the offline token on launch and only re-validate online occasionally.

// license.js (main process)
const { machineIdSync } = require('node-machine-id');
const Store = require('electron-store');
const store = new Store({ encryptionKey: 'your-encryption-key' });

const API_URL = 'https://your-domain.com/api/v1';
const PUB_KEY = 'kb_pub_live_your_publishable_key'; // safe to ship

class LicenseManager {
  constructor() { this.hardwareId = machineIdSync(true); }

  async activate(licenseKey) {
    const res = await fetch(`${API_URL}/licenses/activate`, {
      method: 'POST',
      headers: { Authorization: `Bearer ${PUB_KEY}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({
        license_key: licenseKey,
        hardware_id: this.hardwareId,
        device_name: require('os').hostname(),
        device_metadata: { platform: process.platform, arch: process.arch },
      }),
    });
    const data = await res.json();
    if (data.activated) {
      store.set('license', {
        key: licenseKey,
        token: data.activation_token,   // needed to deactivate later
        offline: data.offline_license,  // verify locally on launch
        keyId: data.key_id,
      });
    }
    return data;
  }

  async validate(licenseKey) {
    const res = await fetch(`${API_URL}/licenses/validate`, {
      method: 'POST',
      headers: { Authorization: `Bearer ${PUB_KEY}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({ license_key: licenseKey, hardware_id: this.hardwareId }),
    });
    return res.json();
  }

  async deactivate(licenseKey) {
    const saved = store.get('license') || {};
    return fetch(`${API_URL}/licenses/deactivate`, {
      method: 'POST',
      headers: { Authorization: `Bearer ${PUB_KEY}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({
        license_key: licenseKey,
        hardware_id: this.hardwareId,
        activation_token: saved.token, // required for publishable keys
      }),
    }).then((r) => r.json());
  }
}

module.exports = new LicenseManager();

// src-tauri/src/license.rs
use serde::{Deserialize, Serialize};
use reqwest::Client;

const API_URL: &str = "https://your-domain.com/api/v1";
const PUB_KEY: &str = "kb_pub_live_your_publishable_key"; // safe to ship

#[derive(Serialize)]
struct ActivateRequest { license_key: String, hardware_id: String, device_name: String }

#[derive(Deserialize)]
pub struct ActivateResponse {
    pub activated: bool,
    pub activation_token: Option<String>,
    pub offline_license: Option<String>,
    pub key_id: Option<String>,
    pub error: Option<String>,
}

pub fn get_hardware_id() -> String {
    machine_uid::get().unwrap_or_else(|_| "unknown".to_string())
}

pub async fn activate(license_key: &str) -> Result<ActivateResponse, String> {
    let device_name = hostname::get().map(|h| h.to_string_lossy().to_string())
        .unwrap_or_else(|_| "Unknown".to_string());
    Client::new()
        .post(format!("{}/licenses/activate", API_URL))
        .header("Authorization", format!("Bearer {}", PUB_KEY))
        .json(&ActivateRequest { license_key: license_key.into(), hardware_id: get_hardware_id(), device_name })
        .send().await.map_err(|e| e.to_string())?
        .json::<ActivateResponse>().await.map_err(|e| e.to_string())
}

# Activate (returns activation_token + offline_license)
curl -X POST https://your-domain.com/api/v1/licenses/activate \
  -H "Authorization: Bearer kb_pub_live_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{"license_key": "XXXX-XXXX-XXXX-XXXX", "hardware_id": "device-123", "device_name": "My PC"}'

# Validate
curl -X POST https://your-domain.com/api/v1/licenses/validate \
  -H "Authorization: Bearer kb_pub_live_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{"license_key": "XXXX-XXXX-XXXX-XXXX", "hardware_id": "device-123"}'

Error codes

Failed validations return an error field with one of these codes:

{ "valid": false, "error": "ACTIVATION_LIMIT_REACHED", "message": "Maximum activations reached (3)" }

Rate limits

Limits are per-IP (publishable keys ship widely, so they are throttled by IP). Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.