Clavem

Documentation

Quickstart

What Clavem does, then the steps to sell your app with license keys: create a product, connect Stripe, and add three calls to your app.

How Clavem works

Clavem gives every buyer of your software a license key, delivers their downloads, and answers your app when it asks whether a key is valid. You keep selling through your own Stripe account.

  1. A customer pays through your Stripe. Checkout, a Payment Link or a subscription, as you already sell.
  2. Clavem creates the license key. The buyer gets an email and an order page with the key and the downloads.
  3. Your app checks the key with Clavem. It sends the key once to activate a device, then at launch to check it is still valid.

A few words used on every page: a product is one thing you sell. A license is one buyer’s right to use it, identified by its license key. Each computer the key is used on is a device, and a product sets how many devices one key may be active on.

Create a product

Create an account and add a product in the dashboard. A product is one thing you sell, such as an app or a plugin. It holds the rules for every license of that product:

  • Device limit. How many machines one key may be active on. The default is 3. Unlimited is allowed.
  • Validity. Perpetual, a fixed number of days, or following the Stripe subscription.

Clavem generates an Ed25519 key pair for the product. Its page shows the public key and the product id. You need both in your app: the key to verify tokens offline, the id to check them.

Connect Stripe and map a product

Create a restricted key in Stripe, paste it into Clavem's settings, and Clavem registers its own webhook in your Stripe account. Then say which Stripe product, or which single price, gives a license for which Clavem product. From then on every paid checkout creates the licenses, the order page and the email. The steps, the permissions the key needs and what each Stripe event does are in Connecting Stripe.

You can skip this step to start. Create a license by hand in the dashboard, or with the management API, and use it for the rest of this page.

Try the License API

The License API needs no secret. The license key is the credential, so nothing sensitive ships in your app. This request uses the demo license that backs the homepage.

Request
curl https://clavem.io/v1/licenses/validate \
  -d license_key="S1GNE-TDEM0-7K4QX-9WZ2P-H5RB8"
Response200 OK
{
  "valid": true,
  "error": null,
  "license_key": {
    "id": 305,
    "status": "active",
    "key": "S1GNE-TDEM0-7K4QX-9WZ2P-H5RB8",
    "activation_limit": 3,
    "activation_usage": 1,
    "created_at": "2026-11-18T23:08:58.988Z",
    "expires_at": null,
    "test_mode": false
  },
  "instance": null,
  "meta": {
    "store_id": 79,
    "order_id": null,
    "order_item_id": 305,
    "product_id": 75,
    "product_name": "Inkwell",
    "variant_id": 75,
    "variant_name": "Default",
    "customer_id": 69,
    "customer_name": "Ada Lovelace",
    "customer_email": "ada@example.com"
  },
  "token": "sgt1.eyJ2IjoxLCJsaWQiOjMwNSwicGlkIjo3NSwi…"
}

The token is shortened here. Apart from token, the response follows the shape of the Lemon Squeezy License API. token is the addition: a signed statement your app can check without calling anyone. Every field is described in the API reference.

Add the three calls

All three are POST requests to https://clavem.io/v1/licenses/. They accept JSON or form-encoded bodies.

CallWhenSend
activateOnce per device, when the customer enters their key.license_key, instance_name, optionally fingerprint
validateAt every launch, and whenever you need to know the current status.license_key, optionally instance_id
deactivateWhen the customer moves the license to another machine.license_key, instance_id

instance_name is for people: it is what your customer sees on the device page. fingerprint is for machines. Send a stable, hashed device identifier and activating twice on the same machine returns the same seat instead of using a second one. Store the instance.id from the response and send it with every validate.

Activate
curl https://clavem.io/v1/licenses/activate \
  -d license_key="YOUR-LICENSE-KEY" \
  -d instance_name="Ada's MacBook Pro" \
  -d fingerprint="9f2c1e0b7a"

The launch-time flow

This is the pattern we recommend. It keeps honest customers running through outages and still notices a revoked license.

  1. On first run there is no stored license. Ask for the key, call activate, and store the key, the instance.id and the token.
  2. On every later launch, call validate with a short timeout.
  3. If it answers valid: true, store the new token and carry on. A fresh token restarts the 14-day window.
  4. If it answers valid: false, the license is expired or disabled. Store the new token, which now says so offline too, tell the customer why using error, and keep the key: a renewal can revive it.
  5. If it answers 404, the key is unknown or this device's activation was removed. Clear what you stored and ask for the key again.
  6. If you got no answer (no network, a 429 or a 5xx), verify the stored token offline. If the signature is good, valid is true, exp has not passed and refresh_by is in the future, carry on.
  7. If refresh_by has passed, ask the customer to connect once. That is the 14-day re-validation.
license.js
// verifyToken and isLicensed are on the offline verification page.
import { verifyToken, isLicensed } from './verify-token.js';

const BASE = 'https://clavem.io';
const PUBLIC_KEY = 'kq1…your key…9fA'; // from your product page
const PRODUCT_ID = 75; // from your product page

// Replace with your platform's secure storage: Keychain, safeStorage, a file in the app data folder.
const store = {
  load: () => JSON.parse(localStorage.getItem('license') ?? 'null'),
  save: (value) => localStorage.setItem('license', JSON.stringify(value)),
  clear: () => localStorage.removeItem('license'),
};

async function call(action, body) {
  const res = await fetch(BASE + '/v1/licenses/' + action, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify(body),
    signal: AbortSignal.timeout(8000),
  });
  return { status: res.status, body: await res.json() };
}

// 1. Once per device, when the customer pastes their key.
export async function activate(licenseKey, deviceName) {
  const { body } = await call('activate', { license_key: licenseKey, instance_name: deviceName });
  if (!body.activated) throw new Error(body.error);
  store.save({ licenseKey, instanceId: body.instance.id, token: body.token });
}

// 2. At every launch. Returns 'licensed', 'invalid', 'needs-network' or 'unlicensed'.
export async function checkLicense() {
  const saved = store.load();
  if (!saved) return 'unlicensed';
  try {
    const { status, body } = await call('validate', { license_key: saved.licenseKey, instance_id: saved.instanceId });
    if (status === 200) {
      // Keep the new token even when the license is not valid: offline, it then says so.
      // A valid one also restarts the 14 days. An expired license keeps its key, because a renewal can revive it.
      store.save({ ...saved, token: body.token });
      return body.valid ? 'licensed' : 'invalid';
    }
    if (status === 404) {
      store.clear(); // the key is unknown or this device was removed: ask for the key again
      return 'invalid';
    }
  } catch {
    // No network.
  }
  // Offline, rate limited or the service is down: trust the stored token while it is fresh.
  const claims = await verifyToken(saved.token, PUBLIC_KEY);
  return isLicensed(claims, PRODUCT_ID) ? 'licensed' : 'needs-network';
}

// 3. When the customer moves the license to another machine.
export async function deactivate() {
  const saved = store.load();
  if (!saved) return;
  await call('deactivate', { license_key: saved.licenseKey, instance_id: saved.instanceId });
  store.clear();
}

The same flow in Swift, Electron, Rust, PHP and Python is in the platform guides. The token checks are on the offline verification page.

Plan limits never block validation. The License API is rate limited per IP address and per key (see the reference), so validate once per launch rather than in a loop. Decide in advance what your app does when it cannot get an answer. Failing open for a fixed window, as above, is kinder than a locked screen.

Test a purchase

  1. Connect Stripe with a test mode key. Licenses it creates are marked test_mode: true.
  2. Buy the product through your Checkout page or Payment Link with a Stripe test card.
  3. Open Licenses in the dashboard. The new license is there, with a link to the order page.
  4. Paste the key into your app, activate, then restart it with the network off to see the offline path.
  5. Refund the payment in Stripe. The license becomes disabled, and the next validate says so.

What your customers see

  • An email and an order page. The page is private to the buyer. It shows the license as a certificate with a copy button, the downloads for your latest release, and your activation instructions.
  • A device page at /licenses/manage. They enter their key, see which machines use it, and remove one. No account and no email round trip, so "I changed computers" does not need you.