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.
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…" }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" }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.
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.
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": {
"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 }
}
}| Code | HTTP | Meaning |
|---|---|---|
| unauthorized | 401 | Missing, malformed or revoked API key |
| forbidden | 403 | Key lacks the required scope |
| invalid_request | 400 | Body failed validation, see details |
| license_not_found | 404 | No license matches that key |
| license_revoked | 403 | Refunded or manually revoked |
| license_expired | 403 | Past expiry and outside any grace period |
| activation_limit_reached | 409 | All seats in use |
| plan_limit_reached | 402 | Your LicenseKit plan is full |
| rate_limited | 429 | Back 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.
X-RateLimit-Limit: 1200
X-RateLimit-Remaining: 1194
X-RateLimit-Reset: 1789412400A 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
{ "key": "ACME-…", "product_id": "acme-studio",
"fingerprint": "…", "require_activation": false }Always 200 for a well-formed request. Read `valid` and `reason`.
{ "key": "ACME-…", "fingerprint": "…",
"platform": "macOS 15.3", "app_version": "2.1.0",
"include_certificate": true }Idempotent per fingerprint. Safe to call on every launch.
{ "key": "ACME-…", "fingerprint": "…" }Frees the seat. Wire this to your 'deactivate this machine' menu item.
{ "key": "ACME-…", "fingerprint": "…" }Returns a signed certificate plus the product public key.
{ "product_id": "acme-studio", "customer_email": "…",
"max_activations": 3, "duration_days": 365 }Issues a key. Returns 402 if your plan is full.
?limit=25&offset=0&status=active&q=buyer@example.comNewest first. `q` searches key, name and email.
{ "status": "suspended" }
{ "extend_days": 365 }
{ "max_activations": 5 }Suspend, revoke, restore, extend, reassign, resize.
—Revokes and releases all seats. The row is kept as your audit trail.
—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.
-----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. Ed25519-verify
signatureoverpayloadwith your product public key. - 2. Decode the payload and check
not_afteris in the future. - 3. Check
license.expires_atif it is set. - 4. Check
license.status === "active". - 5. If the certificate is machine-bound, compare
machine.fingerprint. - 6. Refresh in the background when
not_afteris 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.
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();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"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)// 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));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.
https://licensekit.dev/api/integrations/lemonsqueezy/tok_8f3a…| Store | Verification | Issues on |
|---|---|---|
| Lemon Squeezy | HMAC-SHA256 signing secret | order_created, subscription_created |
| Paddle | Paddle-Signature, 5 min window | transaction.completed |
| Polar | Standard Webhooks signature | order.created, subscription.active |
| Stripe | Stripe-Signature, 5 min window | checkout.session.completed |
| Gumroad | URL 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.
webhook-id: msg_10294
webhook-timestamp: 1789412400
webhook-signature: v1,g0hM9SsE+OTD…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.
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.