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.
- Two doors. An unauthenticated door for the app and a secret-key door for the seller. Never put management actions behind the first.
- Status in HTTP, detail in the body. Use 404 for an unknown key and 400 for a malformed request. Use 200 with
valid: falsefor a known key that is expired or disabled, so the app can show a reason and a renewal path. - One shape for all errors. The client should never need two parsers.
- 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.
- 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.
- 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.
- 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 withRetry-Afterfor temporary failures. - 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.
- Forgive typing, not guessing. Trim whitespace, ignore case, and map characters people confuse, such as O and 0. Do not guess missing characters.
- 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
validmust still find it. New fields such astokenare safe because old apps ignore them. - Version the signed token separately. Clavem’s token starts with the prefix
sgt1and carries avclaim, 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.