LicenseKit

Documentation

The whole API is nine endpoints. Four of them are the ones your application calls; the rest are for your own backend and the dashboard. Base URL: https://licensekit.dev

Quickstart

Five minutes from signup to a working license check. Create your API key in the dashboard first — it is shown once.

1. Create a product
curl https://licensekit.dev/v1/products \
  -H "Authorization: Bearer $LICENSEKIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Studio", "key_prefix": "ACME" }'

# => { "id": "prod_…", "slug": "acme-studio",
#      "signing_public_key": "MCowBQYDK2VwAyEA…" }
2. Issue a license
curl https://licensekit.dev/v1/licenses \
  -H "Authorization: Bearer $LICENSEKIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "acme-studio",
    "customer_email": "buyer@example.com",
    "max_activations": 3
  }'

# => { "key": "ACME-K7QM2-9XTRF-B4HDW-PN3ZC", "status": "active" }
3. Check it from your app
curl https://licensekit.dev/v1/licenses/validate \
  -H "Content-Type: application/json" \
  -d '{ "key": "ACME-K7QM2-9XTRF-B4HDW-PN3ZC" }'

# => { "valid": true, "license": { "status": "active", … } }

That is the whole loop. Everything after this is about seats, refunds and working offline.

Authentication

There are two kinds of request, and the difference matters for your security.

Secret keyAuthorization: Bearer lk_live_…

Full read and write access to your account. Used for issuing, listing, revoking and extending licenses. It belongs on your server or in a CI secret and never inside a shipped binary — anyone who extracts it can mint themselves a license.

No keyvalidate · activate · deactivate · certificate

These four take the license key itself as the credential, because a distributed application cannot hold a secret. They are rate limited per IP and per license, and can only ever read or change the one license whose key was supplied.

Keys are scoped. A key limited to licenses:read can list and look up but cannot issue or revoke — handy for a status page or an internal support tool.

Errors

Every error uses the same envelope. Switch on error.code, never on the message.

Error shape
{
  "error": {
    "code": "activation_limit_reached",
    "message": "All 3 seats on this license are in use. Deactivate another machine first.",
    "details": { "seats_used": 3, "seats_total": 3 }
  }
}
CodeHTTPMeaning
unauthorized401Missing, malformed or revoked API key
forbidden403Key lacks the required scope
invalid_request400Body failed validation, see details
license_not_found404No license matches that key
license_revoked403Refunded or manually revoked
license_expired403Past expiry and outside any grace period
activation_limit_reached409All seats in use
plan_limit_reached402Your LicenseKit plan is full
rate_limited429Back off, see Retry-After

One deliberate exception: POST /v1/licenses/validate answers 200 with { "valid": false, "reason": … } instead of an error status. A revoked license is a business outcome, and returning 200 keeps naive client code from treating “revoked” and “server unreachable” as the same thing.

Rate limits

Authenticated requests are limited per API key by plan. Unauthenticated license checks are limited twice: per IP, and per license.

Response headers
X-RateLimit-Limit: 1200
X-RateLimit-Remaining: 1194
X-RateLimit-Reset: 1789412400

A 429 carries Retry-After in seconds. If you are hitting the per-license limit, you are almost certainly validating in a loop — validate on launch and then rely on a cached offline certificate.

API reference

POST/v1/licenses/validateNone
{ "key": "ACME-…", "product_id": "acme-studio",
  "fingerprint": "…", "require_activation": false }

Always 200 for a well-formed request. Read `valid` and `reason`.

POST/v1/licenses/activateNone
{ "key": "ACME-…", "fingerprint": "…",
  "platform": "macOS 15.3", "app_version": "2.1.0",
  "include_certificate": true }

Idempotent per fingerprint. Safe to call on every launch.

POST/v1/licenses/deactivateNone
{ "key": "ACME-…", "fingerprint": "…" }

Frees the seat. Wire this to your 'deactivate this machine' menu item.

POST/v1/licenses/certificateNone
{ "key": "ACME-…", "fingerprint": "…" }

Returns a signed certificate plus the product public key.

POST/v1/licenseslicenses:write
{ "product_id": "acme-studio", "customer_email": "…",
  "max_activations": 3, "duration_days": 365 }

Issues a key. Returns 402 if your plan is full.

GET/v1/licenseslicenses:read
?limit=25&offset=0&status=active&q=buyer@example.com

Newest first. `q` searches key, name and email.

PATCH/v1/licenses/:keylicenses:write
{ "status": "suspended" }
{ "extend_days": 365 }
{ "max_activations": 5 }

Suspend, revoke, restore, extend, reassign, resize.

DELETE/v1/licenses/:keylicenses:write
—

Revokes and releases all seats. The row is kept as your audit trail.

GET/v1/meany
—

Whoami plus current usage. The cheapest way to test a key.

Offline verification

Calling validate on every launch makes your application depend on our uptime. Do not do that. Fetch a signed certificate, cache it on disk, and verify it locally.

Certificate format
-----BEGIN LICENSE FILE-----
eyJhbGciOiJlZDI1NTE5IiwicGF5bG9hZCI6ImV5SjJJam94TENKaFkyTnZkVzUw
…
-----END LICENSE FILE-----

The base64 decodes to { alg, payload, signature }. The signature is Ed25519 over the base64 payload string, which is itself base64 JSON. Signing the encoded form rather than the raw JSON means verification never depends on key ordering or whitespace.

Verification checklist

  1. 1. Ed25519-verify signature over payload with your product public key.
  2. 2. Decode the payload and check not_after is in the future.
  3. 3. Check license.expires_at if it is set.
  4. 4. Check license.status === "active".
  5. 5. If the certificate is machine-bound, compare machine.fingerprint.
  6. 6. Refresh in the background when not_after is within a few days.

Skipping step 5 is a real weakness: without it, one customer's certificate file works on every machine. Bind it unless you have a reason not to.

Client snippets

There is no SDK to install. Verification is about twenty lines in every language that ships Ed25519 in its standard library — which is all of them now. Copy the one you need.

TypeScript / Node
import { createPublicKey, verify } from "node:crypto";

const SPKI = Buffer.from("302a300506032b6570032100", "hex");
const publicKey = createPublicKey({
  key: Buffer.concat([SPKI, Buffer.from(PUBLIC_KEY_B64, "base64")]),
  format: "der",
  type: "spki",
});

const { payload, signature } = JSON.parse(
  Buffer.from(stripPemWrapper(certificate), "base64").toString("utf8"),
);

const ok = verify(null, Buffer.from(payload, "utf8"), publicKey,
                  Buffer.from(signature, "base64"));

const claims = JSON.parse(Buffer.from(payload, "base64").toString("utf8"));
const fresh  = new Date(claims.not_after) > new Date();

if (ok && fresh && claims.license.status === "active") unlock();
Python
from base64 import b64decode
import json
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
from cryptography.exceptions import InvalidSignature

public_key = Ed25519PublicKey.from_public_bytes(b64decode(PUBLIC_KEY_B64))
envelope = json.loads(b64decode(strip_pem(certificate)))

try:
    public_key.verify(
        b64decode(envelope["signature"]),
        envelope["payload"].encode(),
    )
except InvalidSignature:
    raise SystemExit("tampered license file")

claims = json.loads(b64decode(envelope["payload"]))
assert claims["license"]["status"] == "active"
Go
import (
    "crypto/ed25519"
    "encoding/base64"
    "encoding/json"
)

pub, _ := base64.StdEncoding.DecodeString(publicKeyB64)
raw, _ := base64.StdEncoding.DecodeString(stripPEM(certificate))

var env struct {
    Payload   string `json:"payload"`
    Signature string `json:"signature"`
}
json.Unmarshal(raw, &env)

sig, _ := base64.StdEncoding.DecodeString(env.Signature)
ok := ed25519.Verify(ed25519.PublicKey(pub), []byte(env.Payload), sig)
C# / .NET
// NSec.Cryptography or BouncyCastle both work.
var publicKey = PublicKey.Import(
    SignatureAlgorithm.Ed25519,
    Convert.FromBase64String(PublicKeyB64),
    KeyBlobFormat.RawPublicKey);

var envelope = JsonSerializer.Deserialize<Envelope>(
    Convert.FromBase64String(StripPem(certificate)));

bool ok = SignatureAlgorithm.Ed25519.Verify(
    publicKey,
    Encoding.UTF8.GetBytes(envelope.Payload),
    Convert.FromBase64String(envelope.Signature));
Swift
import CryptoKit

let key = try Curve25519.Signing.PublicKey(
    rawRepresentation: Data(base64Encoded: publicKeyB64)!)

let envelope = try JSONDecoder().decode(
    Envelope.self, from: Data(base64Encoded: stripPem(certificate))!)

let ok = key.isValidSignature(
    Data(base64Encoded: envelope.signature)!,
    for: Data(envelope.payload.utf8))

Store integrations

Connect a store in the dashboard and you get a URL with a random token in it. Paste that into your store's webhook settings. Paid orders become licenses; refunds, chargebacks and cancellations revoke them.

Webhook URL
https://licensekit.dev/api/integrations/lemonsqueezy/tok_8f3a…
StoreVerificationIssues on
Lemon SqueezyHMAC-SHA256 signing secretorder_created, subscription_created
PaddlePaddle-Signature, 5 min windowtransaction.completed
PolarStandard Webhooks signatureorder.created, subscription.active
StripeStripe-Signature, 5 min windowcheckout.session.completed
GumroadURL token only (Gumroad signs nothing)sale ping

Every integration is replay-safe: the store's order id is stored on the license under a unique index, so a webhook delivered three times still produces exactly one key. Quantity above one becomes that many seats.

A note on Gumroad

Gumroad's Ping has no signature scheme, so the token in the URL is the only credential. Treat that URL as a secret, and rotate it from the dashboard if it ever ends up somewhere public.

Outbound webhooks

Point LicenseKit at your own endpoint to hear about license state changes. Signed to the Standard Webhooks spec, so any off-the-shelf verifier works.

Headers
webhook-id: msg_10294
webhook-timestamp: 1789412400
webhook-signature: v1,g0hM9SsE+OTD…
Verify
const signed = `${id}.${timestamp}.${rawBody}`;
const expected = crypto.createHmac("sha256", secret)
                       .update(signed).digest("base64");

// Reject anything older than five minutes, then compare in constant time.

Events: license.created, license.updated, license.revoked, license.suspended, license.restored, license.activated, license.deactivated, license.activation_limit_reached, certificate.issued.

Deliveries retry six times over about nine hours with jittered backoff. An endpoint that fails fifteen times in a row is disabled and shows up in the dashboard. Successful validations are deliberately not delivered — that is thousands of events a day and none of them are interesting.

Machine fingerprints

A fingerprint is any stable string that identifies one installation. It is stored as-is, so do not put anything personal in it — hash whatever you derive it from.

Reasonable sources
macOS    IOPlatformUUID
Windows  MachineGuid (HKLM\SOFTWARE\Microsoft\Cryptography)
Linux    /etc/machine-id
Any      sha256(hostname + primaryMacAddress + installDir)

Avoid anything that changes on a routine basis — a DHCP address, a container id, a session token. A fingerprint that rotates burns a seat every time your customer reboots, and that is the number one cause of “my license stopped working” tickets in every licensing system ever built.

Still stuck? The dashboard activity feed shows every check with its fingerprint and result, which is usually enough to see what is going on.