Clavem

License API design: the Lemon Squeezy, Keygen and Clavem styles compared

A license API answers one question many times a day: is this key valid for this device right now. The designs differ in encoding, error shape and how they report an unknown key, and those details decide how much code every app has to carry.

The job of a license API

A license API serves two kinds of caller. The customer’s app calls it from their machine to activate, validate and deactivate. The seller’s own systems call it to create licenses, look them up and change them. The two callers trust different things and should use different doors.

That split is the first design decision. The app-facing door has no secret, because anything shipped in an app can be read. The seller-facing door uses a secret key and must never run in a client.

Three styles side by side

Lemon Squeezy Keygen Clavem
Base path /v1/licenses/validate on api.lemonsqueezy.com /v1/accounts/<account>/licenses/actions/validate-key /v1/licenses/validate
Request body Form-encoded, Accept: application/json JSON:API, application/vnd.api+json, with meta.key Form-encoded or JSON
Response shape Flat: valid, error, license_key, meta JSON:API with meta.valid, meta.code, data Flat, the same as Lemon Squeezy, plus token
Result signal Boolean plus an error string A machine-readable meta.code such as VALID, EXPIRED, SUSPENDED, NOT_FOUND Boolean plus an error string
Rate limit 60 requests per minute Not covered here 120 per minute per IP and 60 per minute per key

All three come from each project’s documentation as of November 2026. The difference in style is real. Lemon Squeezy and Clavem keep a small flat shape that any HTTP client can read. Keygen follows the JSON:API standard and gives a stable code for each failure, which is more precise and needs a client that expects the format.

Keygen’s codes are worth studying even if you never use it. Its documentation lists VALID, NOT_FOUND, SUSPENDED, EXPIRED and OVERDUE, among others. A code is easier to branch on than an English sentence, and Clavem’s own documentation gives the same advice about its flat shape: do not parse the error text for logic, branch on the HTTP status and on valid.

Real responses

These are live responses from Clavem and Lemon Squeezy, captured on 19 November 2026. The unknown-key request is identical on both.

curl -X POST https://clavem.io/v1/licenses/validate \
  -H "Accept: application/json" \
  -d license_key=00000000-0000-4000-8000-000000000000

Both services answered:

{"valid":false,"error":"license_key not found."}

with HTTP status 404. A request with no key shows a difference:

Service Status Body
Lemon Squeezy 422 {"message":"The license key field is required.","errors":{"license_key":["The license key field is required."]}}
Clavem 400 {"valid":false,"error":"license_key: Invalid input: expected string, received undefined"}

Lemon Squeezy’s validation errors come in a framework’s usual envelope, and Clavem keeps its own flat shape for every error, so an app reads valid and error in every case. That is one fewer branch to maintain.

A successful validate on Clavem returns these headers:

content-type: application/json
cache-control: no-store
access-control-allow-origin: *

no-store matters because a cached answer would defeat the point of asking. access-control-allow-origin: * is deliberate, so Electron renderers, browser extensions and web apps can call the API directly.

Ten rules for a license API

If you are building your own, or judging one, check these.

  1. Two doors. An unauthenticated door for the app and a secret-key door for the seller. Never put management actions behind the first.
  2. Status in HTTP, detail in the body. Use 404 for an unknown key and 400 for a malformed request. Use 200 with valid: false for a known key that is expired or disabled, so the app can show a reason and a renewal path.
  3. One shape for all errors. The client should never need two parsers.
  4. Make activation idempotent. Accept a fingerprint, and return the existing seat when the fingerprint is already active. Retried requests and reinstalls then do not leak seats.
  5. Evaluate expiry at read time. Compute the status when the license is read, not from a scheduled job, so the answer changes the moment the date passes.
  6. Sign the answer. A signed token with the product, status and an expiry lets the app run offline and makes forged responses detectable. See why sign license responses.
  7. Rate limit by both IP and key. Per-IP limits stop a single abuser, and per-key limits stop a loop in one customer’s app from hurting others. Return 429 with Retry-After, and 503 with Retry-After for temporary failures.
  8. Make keys unguessable. A 25-character Crockford base32 key carries 125 random bits, so a “not found” response is not a practical way to enumerate keys.
  9. Forgive typing, not guessing. Trim whitespace, ignore case, and map characters people confuse, such as O and 0. Do not guess missing characters.
  10. Never block validation for a business reason. A plan limit or an unpaid invoice on the seller’s side must not stop customers’ apps from validating. Clavem’s rule is that plan limits never affect the License API.

Status model

A license has four states, and the order of checks is part of the contract.

Status Valid Meaning
inactive Yes Issued, no device active
active Yes At least one device active
expired No The expiry has passed or the subscription ended
disabled No Revoked, or the order was fully refunded

Precedence is disabled, then expired, then active or inactive. A disabled license stays disabled until someone enables it, whatever the payment system says. An expired license comes back to life when a renewal is paid or the expiry moves forward. Without a stated precedence, two engineers will implement it two ways.

Why Clavem copied the Lemon Squeezy shape

Clavem’s License API uses the same paths, parameters and response fields as the Lemon Squeezy License API, and adds a token to responses and a fingerprint to activation. The reason is practical: apps already call that shape, and a hostname change is the cheapest migration for them. The cost is that Clavem inherits some of the original’s looseness, such as a boolean in place of a code. The signed token is where the more precise, machine-checkable answer lives.

Designing for apps that never update

A license API has an unusual constraint: its clients are shipped binaries, and some customers never update them. Whatever paths, fields and error shapes you publish today will be called by apps built years ago. That changes what counts as a safe change.

  • Add fields, never rename or remove them. An app that reads valid must still find it. New fields such as token are safe because old apps ignore them.
  • Version the signed token separately. Clavem’s token starts with the prefix sgt1 and carries a v claim, currently 1, and the documentation tells apps to reject any other value. A future format can then arrive without old apps misreading it.
  • Keep the old hostname alive. Moving to a new domain strands every installed app. Clavem’s earlier workers.dev address stays enabled for a related reason: Stripe webhooks registered before the custom domain existed still point at it.
  • Treat error text as display only. Apps that parse sentences break when you fix a typo.

This is also the argument for the Lemon Squeezy-compatible shape: its clients already exist, so a service that matches it needs no new client code.

Doing this with Clavem

If you are shipping an app and do not want to build the server, the API reference lists every endpoint, field and status. If you are building your own, the ten rules above are the ones that are expensive to change later, because they are compiled into shipped apps.

Questions

Should an unknown license key return a 404 or a 200 with valid false?

Both are used. Clavem, like Lemon Squeezy, returns HTTP 404 with a flat body for an unknown key and HTTP 200 with valid false for a known key that is expired or disabled. The split lets an app tell a mistyped key from a license that exists but has lapsed.

Why does a license API need no authentication?

The license key is the credential, and the app has to call the API from the customer's machine. A secret shipped in the app would not stay secret. Calls that change data for the seller, such as creating licenses, use a separate management API with a bearer key.

What makes activation safe to call twice?

A device fingerprint. If an activation request carries a fingerprint that is already active on the license, the server returns that seat instead of using another.

Sources

  1. Lemon Squeezy License API documentation (as of November 2026)
  2. Keygen API reference, licenses and validate-key (as of November 2026)