# Paperkey: integration spec (machine-readable)

> Software licensing API for local-first apps. License keys for desktop apps, CLI tools, IDE extensions, and plugins. REST API documented with OpenAPI 3.1. Your AI agent (Claude Code, Cursor, ChatGPT) handles the wiring. Open-source TypeScript SDK and MCP server included. A Keygen, Cryptlex, or Lemon Squeezy alternative, built indie-dev first.

This file is the canonical, machine-readable integration spec for Paperkey.
It is intended for users who want their AI assistant (Claude Code, Cursor,
Lovable, n8n, ChatGPT, Gemini, etc.) to help integrate Paperkey. Every
endpoint, payload, error code, and code sample is here.

Consent model: the user is the principal at every step. The user creates
the account, issues API keys via the dashboard, and approves any mutation.
The assistant operates with the user's keys; it never acts autonomously.
Mutations (revoke, deactivate, delete) require the user's confirmation.

- Site:      https://paperkey.dev
- Dashboard: https://app.paperkey.dev
- API base:  https://api.paperkey.dev
- SDK:       npm i @paperkeyhq/sdk   (MIT, TypeScript)
- Repo:      https://github.com/paperkeyhq/sdk
- OpenAPI:   https://paperkey.dev/openapi.json   (3.1, machine-readable surface)

================================================================================
1. CONCEPTS: READ THIS FIRST
================================================================================

Paperkey models software licensing with four objects:

  Account     A dashboard user (you, the developer). Holds Products.
  Product     One app or service you license. Owns API keys and Licenses.
  License     A per-customer credential. Has a key, status, expiry, and
              an activation cap.
  Activation  A license bound to one machine fingerprint (one slot of N).

There are TWO authentication realms (never mix them):

  Realm A: Dashboard (server-only)
    JWT in an httpOnly cookie (`paperkey_session`, 7-day TTL)
    OR `Authorization: Bearer <jwt>`. Used for managing products, issuing/revoking
    licenses, configuring webhooks. Lives in YOUR backend or admin tooling. Never
    ship to a client app.

  Realm B: Public API (safe to ship in client apps)
    A public key starting with `pk_…`, sent as
      `Authorization: Bearer pk_…`  OR  `x-api-key: pk_…`
    Used for: validate, activate, deactivate. This is what your shipped app
    (CLI, desktop, mobile, browser extension) calls.

  There is also a SECRET key starting with `sk_…`, returned ONCE when
  you create a product. Use it for elevated server-to-server admin tasks. The
  dashboard never re-displays it. Store it in your secret manager on creation.

License key format: 3 segments × 5 chars + 2-char checksum, Crockford alphabet (no 0/1/I/O),
e.g. `K7WX9-M3NP4-H8TRC-R2`. A product can also set a 5-char `keyPrefix` so
its keys look like `ACME-K7WX9-M3NP4-H8TRC-R2`.

Default `maxActivations` per license: 1.

Fingerprint format (from @paperkeyhq/sdk): `paperkey_fp_v1_<32 hex chars>`. You
can use the SDK helper `getFingerprint()` or pass any stable string you generate
yourself; it is an opaque identifier from Paperkey's view.

================================================================================
2. INSTALL THE SDK (TYPESCRIPT / JAVASCRIPT)
================================================================================

  npm install @paperkeyhq/sdk
  # or: pnpm add @paperkeyhq/sdk
  # or: yarn add @paperkeyhq/sdk

Public exports:

  import {
    createClient,             // factory for the public-API client
    PaperkeyClient,           // class form
    getFingerprint,           // machine fingerprint helper (Node)
    verifyWebhookSignature,   // constant-time HMAC verifier for webhooks
    signWebhookPayload,       // same algo, exposed for replay tests
  } from '@paperkeyhq/sdk';

  import type {
    PaperkeyClientOptions,
    ValidateResult, ActivateResult, DeactivateResult,
    LicenseInfo, ActivationInfo, PaperkeyError,
  } from '@paperkeyhq/sdk';

The SDK wraps the public API (`/v1/*`) and ships a webhook verifier so you
do not have to hand-roll HMAC code. For dashboard/admin endpoints you call
the REST API directly with `fetch` and your JWT or `sk_` key.

================================================================================
3. THE TYPICAL INTEGRATION (READ END-TO-END)
================================================================================

Step 1: Get keys (one-time, dashboard or API)
  Sign up at https://app.paperkey.dev/register, create a Product. The response gives you a
  public key (`pk_…`) and a secret key (`sk_…`). Store both.

Step 2: Issue a license to a customer (server-side, after Stripe/Lemon checkout)
  POST /licenses with your JWT or sk_ key. The response includes the
  generated license key. Email it to the customer.

Step 3: Customer enters the key in your app
  In your shipped app, call POST /v1/licenses/validate then activate.
  Use the public key (`pk_…`) (safe to ship).

Step 4: On every app launch
  Call validate(key, fingerprint). If it returns `{ valid: true }`, run.
  Cache the result for ~24 h to be offline-tolerant; revalidate on next
  network availability.

Step 5: Listen for webhooks
  Configure a webhook URL on the Product. Verify the HMAC signature on
  every delivery (see section 8).

Below: every endpoint, every payload.

================================================================================
4. PUBLIC API: WHAT YOUR SHIPPED APP CALLS (AUTH: PK_ KEY)
================================================================================

Base URL: https://api.paperkey.dev

--- 4.1  POST /v1/licenses/validate ----------------------------------------------

Auth:    Authorization: Bearer pk_…   (or  x-api-key: pk_…)
Request:
  {
    "license_key": "K7WX9-M3NP4-H8TRC-R2",
    "fingerprint": "paperkey_fp_v1_..."     // optional but recommended
  }

200 OK (valid):
  {
    "valid": true,
    "license": {
      "id": "clx...",
      "status": "active",                   // active | suspended | expired | revoked
      "expiresAt": "2026-12-31T00:00:00.000Z" | null,
      "activationsCount": 1,
      "activationsLimit": 3,
      "isActivated": true,                  // is THIS fingerprint already activated?
      "metadata": null | { ... }
    }
  }

200 OK (invalid):
  {
    "valid": false,
    "error": "invalid_key" | "license_revoked" | "license_expired" | "license_suspended",
    "message": "human-readable"
  }

Note: validate returns 200 in BOTH cases. Use `valid` to branch. 4xx is
reserved for malformed requests, auth failure, or rate limit.

--- 4.2  POST /v1/licenses/activate ---------------------------------------------

Auth:    Authorization: Bearer pk_…
Request:
  {
    "license_key": "K7WX9-M3NP4-H8TRC-R2",
    "fingerprint": "paperkey_fp_v1_...",    // REQUIRED here
    "name": "MacBook Pro"                   // optional, shows in dashboard
  }

200 OK:
  {
    "success": true,
    "activation": {
      "id": "clx...",
      "fingerprint": "paperkey_fp_v1_...",
      "name": "MacBook Pro",
      "createdAt": "2026-04-25T12:34:56.000Z"
    },
    "activationsRemaining": 2
  }

403 activation_limit_reached:
  {
    "success": false,
    "error": "activation_limit_reached",
    "message": "All N activation slots are in use",
    "activationsRemaining": 0
  }

Idempotent: re-activating the SAME (license_key, fingerprint) refreshes
`lastCheckAt` on the existing activation and does NOT consume a new slot.
You can call it on every launch if you want to track liveness.

--- 4.3  POST /v1/licenses/deactivate -------------------------------------------

Auth:    Authorization: Bearer pk_…
Request:
  {
    "license_key": "K7WX9-M3NP4-H8TRC-R2",
    "fingerprint": "paperkey_fp_v1_..."
  }

200 OK:
  {
    "success": true,
    "activationsRemaining": 3
  }

Frees a slot so the customer can move to another machine.

================================================================================
5. ADMIN / DASHBOARD ENDPOINTS (AUTH: JWT OR SK_)
================================================================================

Auth header on every admin call:
  Authorization: Bearer <jwt>
The dashboard SPA uses an httpOnly cookie (`paperkey_session`) instead;
server-to-server callers use the Bearer header.

Auth: Sign up, sign in, and inspect the current user.
  POST   /auth/register                                   [public]
      Create a new dashboard account. Returns the user and a JWT.
  POST   /auth/login                                      [public]
      Exchange credentials for a JWT.
  GET    /auth/me                                         [jwt]
      Return the current user; 200 with `{ user: null }` when signed out.
  POST   /auth/logout                                     [jwt]
      Clear the paperkey_session cookie.

Products: A product is the app or service you license.
  GET    /products                                        [jwt]
      List your products.
  POST   /products                                        [jwt]
      Create a product.
      Response includes a secret key (sk_…) shown once only. Store it server-side.
  GET    /products/:id                                    [jwt]
      Get one product with its API keys.
  PATCH  /products/:id                                    [jwt]
      Update name, description, or keyPrefix.
  DELETE /products/:id                                    [jwt]
      Delete a product.
  POST   /products/:id/api-keys                           [jwt]
      Generate a new public/secret key pair (rotation).
  DELETE /products/:id/api-keys/:keyId                    [jwt]
      Revoke a key pair. Apps using it stop working immediately.
  GET    /products/:id/licenses/export?format=json|csv    [jwt]
      Self-custody export. Every license + activation for this product. Always available, no support ticket. Audited.

Licenses: Per-customer credentials issued against a product.
  GET    /licenses?productId=…                            [jwt]
      List licenses for a product.
  POST   /licenses                                        [jwt]
      Issue a new license key (unique, includes a checksum).
  GET    /licenses/:id                                    [jwt]
      Get one license plus up to 100 most-recent activations.
  PATCH  /licenses/:id                                    [jwt]
      Update name, email, expiresAt, metadata.
  POST   /licenses/:id/revoke                             [jwt]
      Revoke (fires license.revoked).
  POST   /licenses/:id/reinstate                          [jwt]
      Reinstate (fires license.reinstated).
  DELETE /licenses/:id/activations/:activationId          [jwt]
      Remove one activation slot (fires activation.removed).

Webhooks: Subscribe to events on a product. Each delivery POSTs JSON with an HMAC-SHA-256 signature.
  GET    /products/:id/webhooks                           [jwt]
      List webhooks on a product.
  POST   /products/:id/webhooks                           [jwt]
      Create a webhook (URL must be HTTPS).
      Returns the webhook plus the secret (shown once).
  PATCH  /products/:id/webhooks/:webhookId                [jwt]
      Pause/resume or change url/events. Resuming clears the failure counter.
  DELETE /products/:id/webhooks/:webhookId                [jwt]
      Delete a webhook.

Webhook events (six):
  - license.created
  - license.revoked
  - license.reinstated
  - license.expired
  - activation.created
  - activation.removed

Headers on every delivery:
  X-Paperkey-Event     event name (e.g. license.created)
  X-Paperkey-Delivery  unique delivery id. Use for idempotency
  X-Paperkey-Signature  hex HMAC-SHA-256 of the raw body using your secret

Delivery semantics:
  - Fire-and-forget. Webhook failures NEVER block the API call that triggered them.
  - 5-second timeout per delivery.
  - 10 consecutive failures auto-pauses the webhook. Resume from dashboard
    or via PATCH (resume clears the failure counter).
  - Each delivery is logged (status, duration, error). Last 100 visible per webhook.
  - Use `X-Paperkey-Delivery` for idempotency. Paperkey may retry on transient
    network errors. Treat duplicate delivery IDs as no-ops.

================================================================================
6. ERRORS: UNIVERSAL SHAPE AND CODES
================================================================================

Every error response:
  {
    "error": "<machine_code>",
    "message": "<human readable>",
    "details": [...]              // optional, e.g. zod issues for validation_error
  }

Common codes:

  validation_error             400  Body failed schema validation. `details` carries zod issues.
  unauthorized                 401  Missing or invalid token / API key.
  forbidden                    403  Authenticated but not allowed.
  not_found                    404  Resource missing or owned by someone else (IDOR-safe).
  activation_limit_reached     403  License is at maxActivations.
  conflict                     409  Email already registered, key collision, etc.
  body_too_large               413  Request body exceeded 64 KB.
  rate_limit_exceeded          429  Per-IP global limit hit.
  auth_rate_limited            429  Too many `/auth/*` hits from one IP.
  license_rate_limited         429  Too many calls per license key.
  internal_error               500  Server bug. Safe to retry with exponential backoff.

Rate limits (defaults pulled from @paperkey/shared/RATE_LIMITS):

  Per IP, global: 100 / min
  Per IP on /auth/*: 5 / 15 min
  Per license on validate: 30 / min
  Per license on activate: 10 / hour
  Per license on deactivate: 10 / hour

Every response includes:
  X-RateLimit-Limit       max requests in the window
  X-RateLimit-Remaining   requests left
  X-RateLimit-Reset       Unix seconds when the window resets

================================================================================
7. CODE SAMPLES
================================================================================

--- 7.1  TypeScript and Node, using the SDK -------------------------------------

  import { createClient, getFingerprint } from '@paperkeyhq/sdk';

  const paperkey = createClient({
    apiKey: process.env.PAPERKEY_PUBLIC_KEY!,   // pk_...
    // baseUrl: 'https://api.paperkey.dev',     // default
    // timeout: 10000,                          // ms, default
  });

  async function gateApp(licenseKey: string) {
    const { fingerprint } = await getFingerprint();      // Node-only helper

    const v = await paperkey.validate(licenseKey, fingerprint);
    if (!v.valid) throw new Error(v.error ?? 'invalid_license');

    if (!v.license?.isActivated) {
      const a = await paperkey.activate(licenseKey, fingerprint, 'My PC');
      if (!a.success) throw new Error(a.error ?? 'activation_failed');
    }

    return v.license;
  }

--- 7.2  TypeScript and Node, without the SDK (raw fetch) -----------------------

  const r = await fetch('https://api.paperkey.dev/v1/licenses/validate', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${process.env.PAPERKEY_PUBLIC_KEY}`,
    },
    body: JSON.stringify({ license_key: key, fingerprint: fp }),
  });
  const data = await r.json();
  if (!data.valid) { /* show paywall */ }

--- 7.3  Python (requests) -----------------------------------------------------

  import os, requests

  PAPERKEY_PK = os.environ["PAPERKEY_PUBLIC_KEY"]   # pk_...
  BASE = "https://api.paperkey.dev"

  def validate(key: str, fingerprint: str) -> dict:
      r = requests.post(
          f"{BASE}/v1/licenses/validate",
          headers={"Authorization": f"Bearer {PAPERKEY_PK}"},
          json={"license_key": key, "fingerprint": fingerprint},
          timeout=10,
      )
      r.raise_for_status()
      return r.json()

  def activate(key: str, fingerprint: str, name: str | None = None) -> dict:
      r = requests.post(
          f"{BASE}/v1/licenses/activate",
          headers={"Authorization": f"Bearer {PAPERKEY_PK}"},
          json={"license_key": key, "fingerprint": fingerprint, "name": name},
          timeout=10,
      )
      r.raise_for_status()
      return r.json()

--- 7.4  Go (stdlib only) ------------------------------------------------------

  package paperkey

  import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
    "time"
  )

  var client = &http.Client{Timeout: 10 * time.Second}

  type ValidateResp struct {
    Valid   bool                   `json:"valid"`
    License map[string]interface{} `json:"license,omitempty"`
    Error   string                 `json:"error,omitempty"`
    Message string                 `json:"message,omitempty"`
  }

  func Validate(key, fp string) (*ValidateResp, error) {
    body, _ := json.Marshal(map[string]string{
      "license_key": key,
      "fingerprint": fp,
    })
    req, _ := http.NewRequest("POST",
      "https://api.paperkey.dev/v1/licenses/validate",
      bytes.NewReader(body))
    req.Header.Set("Authorization", "Bearer "+os.Getenv("PAPERKEY_PUBLIC_KEY"))
    req.Header.Set("Content-Type", "application/json")
    res, err := client.Do(req)
    if err != nil { return nil, err }
    defer res.Body.Close()
    if res.StatusCode != 200 {
      return nil, fmt.Errorf("paperkey: status %d", res.StatusCode)
    }
    var v ValidateResp
    if err := json.NewDecoder(res.Body).Decode(&v); err != nil { return nil, err }
    return &v, nil
  }

--- 7.5  curl, every public endpoint ------------------------------------------

  # Validate
  curl -s https://api.paperkey.dev/v1/licenses/validate \
    -H "Authorization: Bearer $PAPERKEY_PK" \
    -H "Content-Type: application/json" \
    -d '{"license_key":"K7WX9-M3NP4-H8TRC-R2","fingerprint":"paperkey_fp_v1_demo"}'

  # Activate
  curl -s https://api.paperkey.dev/v1/licenses/activate \
    -H "Authorization: Bearer $PAPERKEY_PK" \
    -H "Content-Type: application/json" \
    -d '{"license_key":"K7WX9-M3NP4-H8TRC-R2","fingerprint":"paperkey_fp_v1_demo","name":"My PC"}'

  # Deactivate
  curl -s https://api.paperkey.dev/v1/licenses/deactivate \
    -H "Authorization: Bearer $PAPERKEY_PK" \
    -H "Content-Type: application/json" \
    -d '{"license_key":"K7WX9-M3NP4-H8TRC-R2","fingerprint":"paperkey_fp_v1_demo"}'

--- 7.6  curl, issue a license server-side ----------------------------

  # First, log in to get a JWT (or use a stored sk_ key)
  TOKEN=$(curl -s https://api.paperkey.dev/auth/login \
    -H "Content-Type: application/json" \
    -d '{"email":"you@x.com","password":"..."}' | jq -r .token)

  # Then issue a license
  curl -s https://api.paperkey.dev/licenses \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "productId": "clx...",
      "email": "customer@x.com",
      "maxActivations": 3,
      "expiresAt": "2027-04-25T00:00:00Z"
    }'

================================================================================
8. WEBHOOK VERIFICATION (ALWAYS VERIFY; UNSIGNED EVENTS ARE NOT YOUR EVENTS)
================================================================================

The signature is a hex HMAC-SHA-256 of the RAW request body using the secret
returned to you when you created the webhook. ALWAYS:

  1. Read the RAW body (bytes / string before JSON.parse). Do not re-serialize
     a parsed object; key order/whitespace differences will break the HMAC.
  2. Compare in constant time (`crypto.timingSafeEqual` in Node, `hmac.compare_digest`
     in Python). Never use `===` on raw strings. That is a timing oracle.
  3. Reject anything that fails. 401 is a fine response.

--- 8.0  TL;DR: use the SDK helper (Node) -------------------------------------

On Node with the SDK, the helper replaces the hand-rolled HMAC code:

  import { verifyWebhookSignature } from '@paperkeyhq/sdk';

  // Express:
  app.post('/paperkey-webhook', (req, res) => {
    const ok = verifyWebhookSignature(
      req.body.toString('utf8'),                    // raw body, not parsed
      String(req.headers['x-paperkey-signature'] ?? ''),
      process.env.PAPERKEY_WEBHOOK_SECRET!,
    );
    if (!ok) return res.status(401).end();
    // ... handle event
    res.status(200).end();
  });

It is constant-time, length-checked, and matches Paperkey's signing exactly.
The framework-specific examples below are equivalent and useful if you do not
want the SDK as a dep, or if you are not on Node.

--- 8.1  Node / Express --------------------------------------------------------

  import crypto from 'node:crypto';
  import express from 'express';

  const app = express();
  // IMPORTANT: capture raw body for signature verification
  app.use(express.raw({ type: 'application/json' }));

  const SECRET = process.env.PAPERKEY_WEBHOOK_SECRET!;

  app.post('/paperkey-webhook', (req, res) => {
    const sig = String(req.headers['x-paperkey-signature'] ?? '');
    const expected = crypto.createHmac('sha256', SECRET)
      .update(req.body)                                  // Buffer of raw body
      .digest('hex');

    const a = Buffer.from(sig, 'hex');
    const b = Buffer.from(expected, 'hex');
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
      return res.status(401).end();
    }

    const event = JSON.parse(req.body.toString('utf8'));
    // ... handle event (idempotent: dedupe on event.id or X-Paperkey-Delivery)
    res.status(200).end();
  });

--- 8.2  Next.js App Router (route handler) ------------------------------------

  // app/api/paperkey-webhook/route.ts
  import crypto from 'node:crypto';

  export async function POST(req: Request) {
    const raw = await req.text();
    const sig = req.headers.get('x-paperkey-signature') ?? '';
    const expected = crypto.createHmac('sha256', process.env.PAPERKEY_WEBHOOK_SECRET!)
      .update(raw).digest('hex');
    const ok = sig.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(sig, 'hex'), Buffer.from(expected, 'hex'));
    if (!ok) return new Response('bad signature', { status: 401 });
    const event = JSON.parse(raw);
    // ...
    return new Response(null, { status: 200 });
  }

--- 8.3  Python / Flask --------------------------------------------------------

  import hmac, hashlib, os
  from flask import Flask, request, abort

  SECRET = os.environ["PAPERKEY_WEBHOOK_SECRET"].encode()
  app = Flask(__name__)

  @app.post("/paperkey-webhook")
  def hook():
      raw = request.get_data()                          # bytes, before JSON parse
      sig = request.headers.get("X-Paperkey-Signature", "")
      expected = hmac.new(SECRET, raw, hashlib.sha256).hexdigest()
      if not hmac.compare_digest(sig, expected):
          abort(401)
      event = request.get_json(force=True)
      # ...
      return "", 200

--- 8.4  Go --------------------------------------------------------------------

  import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "io"
    "net/http"
    "os"
  )

  func paperkeyHook(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)
    mac := hmac.New(sha256.New, []byte(os.Getenv("PAPERKEY_WEBHOOK_SECRET")))
    mac.Write(body)
    expected := hex.EncodeToString(mac.Sum(nil))
    sig := r.Header.Get("X-Paperkey-Signature")
    if !hmac.Equal([]byte(sig), []byte(expected)) {
      w.WriteHeader(401); return
    }
    // parse body, handle event
    w.WriteHeader(200)
  }

================================================================================
9. MCP SERVER (DRIVE PAPERKEY FROM CLAUDE DESKTOP, CURSOR, OR CONTINUE)
================================================================================

The MCP server is for users who want to query or mutate Paperkey from natural
language inside an MCP-capable AI client, instead of writing API calls.
The user installs and configures it on their own machine, with their own
dashboard JWT. It speaks to the same admin endpoints documented in section 5.

Install:
  No install step. `npx` runs it directly:
    npx -y @paperkeyhq/mcp

Configuration (Claude Desktop):
  Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
  on macOS, or `%APPDATA%\Claude\claude_desktop_config.json` on Windows.
  Add:

  {
    "mcpServers": {
      "paperkey": {
        "command": "npx",
        "args": ["-y", "@paperkeyhq/mcp"],
        "env": {
          "PAPERKEY_API_TOKEN": "<your dashboard JWT>"
        }
      }
    }
  }

  Restart Claude Desktop. The "paperkey" server appears in the tools menu.

Configuration (Cursor):
  Same JSON, in `.cursor/mcp.json` (per-project) or `~/.cursor/mcp.json`
  (global).

Auth:
  PAPERKEY_API_TOKEN is a dashboard JWT. The user can grab one from
  https://app.paperkey.dev/settings or by calling POST /auth/login. Optional
  PAPERKEY_API_URL overrides the API base (useful for self-host or staging).

Tool surface (read-mostly. Mutating tools require an explicit id, so the
assistant must list or inspect first and cannot act on a guess. Mutations
need the user's confirmation before they hit the API):

  paperkey_list_products                          List your products with id, name, slug, maxActivations, license count.
  paperkey_get_product                            Fetch one product by id including its API keys (public-side only).
  paperkey_list_licenses                          List licenses (filter by productId, status, email).
  paperkey_get_license                            Fetch one license with up to 100 most-recent activations.
  paperkey_find_high_activation_licenses          Find licenses with more than N activations.
  paperkey_revoke_license                         Revoke a license by id (mutating; the assistant must list or inspect first).
  paperkey_reinstate_license                      Reinstate a previously revoked license.
  paperkey_analyze_churn                          Analyze license churn over a window (default 30 days, max 180). Returns markdown + structured metrics with cohort breakdown and baseline comparison.
  paperkey_detect_fraud                           Surface license-sharing and abuse signals over a window (default 30 days, max 90). Returns markdown + signals (fingerprint reuse, multi-IP, near-cap licenses).
  paperkey_generate_audit_report                  Markdown digest of recent account activity over a window (default 7 days, max 90). New licenses, activations, revocations, webhook counts, anomalies.

Use cases:
  - SDK   → the user is building an app that ships to customers (validate,
            activate, deactivate from inside their product).
  - MCP   → the user wants to operate their own Paperkey account from an AI
            client ("revoke alice@acme.io's license", "list licenses with
            >5 activations this week"). It is admin tooling, not a runtime
            integration.

Both apply only when the user is doing both.

Pattern: a single user can both ship the SDK in their app AND wire the MCP
server into their own Claude/Cursor for admin work. The same JWT can power
both during development; in production, scope the SDK to the public key
(pk_…) and keep the JWT off shipped binaries.

================================================================================
10. PATTERNS THAT WORK
================================================================================

Cache validation locally for offline tolerance. Built into the SDK.
  Since @paperkeyhq/sdk v0.3.0, validate() automatically caches the last
  positive verdict and replays it when the live API is unreachable, within
  a 72-hour grace window (configurable via `gracePeriodMs`). Pass
  `fileSystemCache({ path })` to persist across app restarts; the default
  in-memory adapter survives only the current process. Authoritative
  negatives (revocation, expiration, 4xx errors) are NEVER cached. A
  revoked license stays revoked. Result: shipped apps keep running on
  flaky networks (planes, cafés, corporate VPN drops) without you writing
  a line of cache code.

  Example:
    import { createClient, fileSystemCache } from '@paperkeyhq/sdk';
    const paperkey = createClient({
      apiKey: process.env.PAPERKEY_PK!,
      cache: fileSystemCache({ path: app.getPath('userData') }),
    });
    const result = await paperkey.validate(licenseKey, fingerprint);
    if (result.source === 'cache') { /* offline-tolerant fallback fired */ }

Re-activate on every launch (it's free and idempotent).
  activate() returns 200 without consuming a slot when the same fingerprint
  re-activates. Side effect: `lastCheckAt` updates, so the dashboard shows
  liveness. Handy for support.

Issue licenses from your checkout webhook, not from a button.
  Wire your Stripe / Lemon Squeezy / Paddle webhook to POST /licenses on
  `checkout.session.completed`. Email the returned key. No manual step.

Use metadata for tier/plan info.
  `metadata: { plan: "pro", seats: 5 }` is free-form and returned by
  validate(). Branch on it client-side instead of issuing different keys.

Rotate API keys on suspicion.
  POST /products/:id/api-keys → ship the new `pk_` in the next release →
  DELETE the old key once usage drains. The old key dies instantly on delete.

Per-license rate limits are per-key, not per-machine.
  If a key gets stolen and abused, the rate limiter on validate blunts the
  abuse and you'll see it in the audit log. Revoke from the dashboard;
  the customer reissues.

Webhook secrets are NEVER returned by GET.
  If you lose the secret, you must rotate the webhook (delete + recreate)
  and re-store the new secret. There is no "show me the secret again"
  endpoint by design.

================================================================================
11. RECIPES: END-TO-END WORKFLOWS
================================================================================

Each recipe lists the user intent it matches. Each one is the FULL wiring,
not a snippet. The user can drop it in, swap secrets, and ship.

--- 11.1  Stripe Checkout → Paperkey license issuance --------------------------

Intent: "user pays via Stripe, send them a license key by email".

Flow:
  Stripe Checkout (or Subscription) → checkout.session.completed webhook →
  POST /licenses (admin JWT or sk_ key) → email the key.

Hono / Node example (works in any framework. Order matters):

  app.post('/stripe/webhook', async (c) => {
    const sig = c.req.header('stripe-signature') ?? '';
    const body = await c.req.text();
    const event = stripe.webhooks.constructEvent(body, sig, STRIPE_SECRET);

    if (event.type !== 'checkout.session.completed') return c.body(null, 200);

    const session = event.data.object;
    const email = session.customer_details?.email;
    if (!email) return c.body(null, 200);

    const r = await fetch('https://api.paperkey.dev/licenses', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.PAPERKEY_JWT}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        productId: process.env.PAPERKEY_PRODUCT_ID,
        email,
        maxActivations: 3,
        metadata: { stripe_customer: session.customer, plan: session.metadata?.plan },
      }),
    });
    const { license } = await r.json();

    await sendLicenseEmail(email, license.key);  // your transactional email
    return c.body(null, 200);
  });

Idempotency: Stripe retries on 5xx. Either dedupe on event.id, or (easier)
make license creation tolerant of duplicate (productId, email) by listing
first and returning the existing key. License keys are unique per row, so
two webhook fires would create two keys without dedupe.

--- 11.2  Electron / desktop app gate (offline-tolerant) -----------------------

Intent: "license-gate my desktop app, but don't break when the user is offline".

Flow on launch:
  1. Read cached `{ licenseKey, lastValidatedAt, expiresAt }` from disk.
  2. If cache fresh (< 24 h) AND not past expiresAt → run the app.
  3. Else call validate(); on success refresh cache, on failure show paywall.
  4. After successful validate, fire activate(). Idempotent for the same
     fingerprint, so it's free to call on every launch and updates lastCheckAt.

  import { app } from 'electron';
  import { createClient, getFingerprint } from '@paperkeyhq/sdk';
  import { readFile, writeFile } from 'node:fs/promises';
  import { join } from 'node:path';

  const CACHE = join(app.getPath('userData'), 'paperkey-cache.json');
  const TTL_MS = 24 * 60 * 60 * 1000;
  const paperkey = createClient({ apiKey: PAPERKEY_PUBLIC_KEY });

  async function gate(licenseKey: string): Promise<{ ok: true } | { ok: false; reason: string }> {
    const { fingerprint } = await getFingerprint();
    let cache: { lastValidatedAt: number; expiresAt: string | null } | null = null;
    try { cache = JSON.parse(await readFile(CACHE, 'utf8')); } catch { /* no cache */ }

    const cacheFresh =
      cache &&
      Date.now() - cache.lastValidatedAt < TTL_MS &&
      (!cache.expiresAt || new Date(cache.expiresAt) > new Date());

    if (cacheFresh) return { ok: true };

    try {
      const v = await paperkey.validate(licenseKey, fingerprint);
      if (!v.valid) return { ok: false, reason: v.error ?? 'invalid' };
      if (!v.license?.isActivated) {
        const a = await paperkey.activate(licenseKey, fingerprint, app.name);
        if (!a.success) return { ok: false, reason: a.error ?? 'activation_failed' };
      }
      await writeFile(CACHE, JSON.stringify({
        lastValidatedAt: Date.now(),
        expiresAt: v.license?.expiresAt ?? null,
      }));
      return { ok: true };
    } catch {
      // Network down: fall back to cache if it has an expiresAt in the future.
      if (cache && (!cache.expiresAt || new Date(cache.expiresAt) > new Date())) {
        return { ok: true };
      }
      return { ok: false, reason: 'network_unavailable_no_cache' };
    }
  }

Trade-off: a 24-h cache means a revoked license stays runnable for up to 24 h
on a machine that goes offline immediately after revocation. Acceptable for
most B2B desktop apps. Tighten the TTL if your threat model says no.

--- 11.3  Rotate the public/secret API key (zero-downtime) ---------------------

Intent: "I think a key leaked. Rotate without disrupting shipped clients."

  1. POST /products/:id/api-keys                        # creates a new pair
  2. Roll out the new pk_ in your next app release.
  3. Wait until usage drains (audit log on the dashboard shows last-used).
  4. DELETE /products/:id/api-keys/:keyId               # kills the OLD pair

The OLD key 401s instantly on delete. Order matters: never delete before the
new key is shipped, or in-flight clients break.

--- 11.4  Re-seat a license to another machine (support flow) ------------------

Intent: "customer's old laptop died, move their seat to the new one".

  POST /v1/licenses/deactivate
    Body: { license_key, fingerprint: <OLD machine fp> }

  Then on the new machine:
  POST /v1/licenses/activate
    Body: { license_key, fingerprint: <NEW machine fp>, name: "MacBook M4" }

If you do not have the old fingerprint (laptop is gone), use the dashboard
admin endpoint instead:
  DELETE /licenses/:id/activations/:activationId         # frees one slot

This fires `activation.removed` on the customer's webhook so your support
tooling can log it.

--- 11.5  Detect license sharing / churn from the MCP server -------------------

Intent: "find licenses being abused or about to churn, weekly".

If the user runs the Paperkey MCP server in their AI client, two tools cover
this without writing any code:

  paperkey_detect_fraud         # surfaces fingerprint reuse, multi-IP,
                                 # near-cap activation patterns
  paperkey_analyze_churn        # cohort-based churn vs the prior window

These tools are easier than hand-rolling SQL or polling the API. They are
pre-built, parameterized, and return markdown the assistant can render
directly back to the user. Mutations still require the user's confirmation.

================================================================================
12. SUPPORT
================================================================================

  Email:    hello@paperkey.dev
  Twitter:  @paperkeydev
  Web:      https://paperkey.dev
  Status:   https://paperkey.dev (incident banner appears here when applicable)

This file is generated at build time from `apps/web/src/lib/site.ts`,
`apps/web/src/lib/api-spec.ts`, and `@paperkey/shared` constants. Edit those
and rebuild and the spec regenerates. If something here disagrees with the
runtime API, the runtime wins. Email hello@paperkey.dev so we can fix it.