The mistakes at a glance
| # | Mistake | Consequence | Fix |
|---|---|---|---|
| 1 | Short, sequential or structured keys | Anyone can guess or generate keys | Random keys, 100 bits or more, checked on a server |
| 2 | Validating a key with a formula inside the app | A key generator is a matter of time | Check on the server; verify signed tokens in the app |
| 3 | Shipping a signing key, API secret or admin key in the app | Anyone can mint licenses | Ship only a public key; keep secrets on your server |
| 4 | Treating HTTP 200 as “licensed” | Expired and disabled licenses pass | Read the valid flag |
| 5 | Not checking the product id | A key for your cheap product opens your expensive one | Compare pid with your product |
| 6 | Putting the key in URLs | Keys leak through logs and referrers | Use a body or a header |
| 7 | Logging or sending full keys to analytics | Keys leak through third parties | Mask all but a few characters |
| 8 | No rate limiting | Guessing and abuse run unchecked | Limit per IP and per key |
| 9 | Failing closed on errors | An outage locks honest users out | Treat 429 and 5xx as “no answer” and fall back |
| 10 | Using the token as a login session | A copyable string acts as an identity | Bind to a device if you must, and keep it out of your own auth |
| 11 | No way to revoke | Leaked keys work forever | A disable switch and a short refresh window |
| 12 | Normalising the key client-side | Imported keys stop matching | Send the key as typed, trimmed |
The rest of this article takes the ones that need numbers or code.
Mistakes 1 and 2: the key itself
A license key is a credential. In Clavem’s License API the key is the only thing the app sends: there is no separate secret. That makes its randomness the whole defence.
Entropy is the number of bits of randomness in a key. For a key of length characters drawn uniformly from an alphabet of base symbols, it is length × log2(base). I ran a short script for six formats. It also estimates how long an attacker needs to hit any valid key by guessing. Assumptions: 10,000 valid keys exist, the License API limit of 120 requests per minute per IP address, and an attacker with 1,000 IP addresses.
| Format | Random bits | Keyspace | Expected guesses to hit any valid key | Years at 63 billion guesses a year |
|---|---|---|---|---|
| 8 decimal digits | 27 | 1.0e+8 | 10,000 | 1.6e-7 (a few seconds) |
| 8 hex characters | 32 | 4.3e+9 | 429,497 | 6.8e-6 (a few minutes) |
| 16 hex characters | 64 | 1.8e+19 | 1.8e+15 | 29,247 |
| 20 base32 characters | 100 | 1.3e+30 | 1.3e+26 | 2.0e+15 |
| 25 base32 characters (Clavem) | 125 | 4.3e+37 | 4.3e+33 | 6.7e+22 |
| UUID v4 (122 random bits) | 122 | 5.3e+36 | 5.3e+32 | 8.4e+21 |
Divide the keyspace by the number of valid keys to get the expected number of guesses. A format with 27 bits and 10,000 valid keys needs about 10,000 guesses. One IP address at 120 a minute does that in about 83 minutes, and a thousand addresses do it in seconds. At 100 bits and above, the numbers are out of reach even for a large botnet.
The rate limit is not the main protection. The keyspace is. Sixty-four bits already look comfortable in the table, though I would still choose more because the cost of extra characters is nothing.
Mistake 2 is the same idea in another form: a key that the app validates with a checksum or an algorithm. Anyone who disassembles the app can reproduce the algorithm and generate keys. This is what a keygen is. Random keys that only a server can recognise cannot be generated.
Mistake 3: secrets in the app
Whatever you ship can be read. The only values that belong in the app are the product id and the product’s public key. A public key verifies signatures and cannot create them.
Clavem’s License API does not need a secret from the app, so there is nothing to hide there. The management API uses a secret key that starts with sk_clavem_, and it belongs only on your server. If an sk_ key ends up in a desktop app, a browser extension or a mobile bundle, assume it is public: revoke it under Developers in the dashboard and create a new one. The management API sends no CORS headers on purpose, because a browser should never call it.
Mistake 4: trusting the status code
A known key always answers HTTP 200, whether or not it is valid. Here is the answer for an expired license, which still has status 200:
{
"valid": false,
"error": "This license key has expired.",
"license_key": { "status": "expired", "…": "…" },
"token": "sgt1.…"
}
An app that only checks res.ok treats every known key as licensed. Read valid. For activation, read activated. Branch on the HTTP status for unknown keys (404) and malformed requests (400), and on valid for everything else. Do not parse the error sentence for logic. The API reference lists every status and error.
Mistake 5: not checking the product
A signature proves that Clavem issued a token. It does not prove the token is for your product. If you sell two products and a buyer of the cheap one presents its token to the expensive one, only the pid claim says no. Compare it with the constant for your product. Why sign license responses shows the failure in a demo.
Mistakes 6 and 7: where keys leak
URLs are logged by servers, proxies and browsers, and they travel in referrer headers. The License API takes the key in a POST body. The releases endpoint accepts it in the X-License-Key header, and the license_key query parameter is legacy. Use the header.
In your own telemetry, never send the whole key. Keep the first and last few characters, enough for you to recognise it in a support request:
const mask = (key) => key.slice(0, 5) + '…' + key.slice(-5);
mask('S1GNE-TDEM0-7K4QX-9WZ2P-H5RB8'); // 'S1GNE…H5RB8'
Mistakes 8 and 9: rate limits and failing closed
Clavem’s License API allows 120 requests per 60 seconds per IP address, and 60 per 60 seconds per license key. A request has to pass both. Past a limit, the answer is 429 with Retry-After: 60. The per-key limit stops one key being hammered, and the per-IP limit slows guessing. Neither is a quota: plan limits never affect the License API.
Your app should call validate once at launch with a short timeout, not in a loop. Treat 429, 503 (which carries Retry-After: 5) and network errors as “no answer”, not “unlicensed”. Fall back to the stored token while it is fresh. If your app fails closed on these, an outage becomes a support wave. See offline license checks explained.
Mistake 10: tokens as sessions
A token is a signed statement, readable by anyone who has it, and not bound to a device. Do not use it as the credential to your own backend, and do not log it. If you need it tied to a machine, compare iid or fp in the payload with what your app stored at activation.
Mistake 11: no way to revoke
Keys leak and payments get refunded. You need a switch. In Clavem, a full Stripe refund disables the licenses from that order, and you can disable any license from the dashboard or with PATCH /v1/admin/licenses/:id and { "disabled": true }. The change reaches an online app on its next validate, and an offline one when its token needs refreshing, at most 14 days.
Mistake 12: normalising the key yourself
Clavem trims the key and matches it without regard to case. Keys it generates also forgive the usual misreadings: I and L read as 1, O as 0, U as V. Imported keys, such as Lemon Squeezy UUIDs, match as written, lower-cased. If your app rewrites O to 0 before sending, an imported key containing an O stops matching. Send what the buyer typed, trimmed.
Doing this with Clavem
The points above are defaults here: random 25-character keys, server-side checks, Ed25519 tokens, per-IP and per-key rate limits, a valid flag, sk_clavem_ management keys that never need to be in an app, and a disable switch. What stays your job is the app side: reading valid, checking pid, masking keys in logs and choosing the fallback. The key format checker helps when you are designing your own format.
Questions
How long should a license key be?
Long enough that guessing a valid one is impractical. A key with 100 or more random bits is out of reach of online guessing. Clavem's keys are 25 characters of Crockford base32, which is 125 bits. Length for its own sake matters less than randomness and a server-side check.
Is it safe to put the license key in a URL?
Avoid it. URLs end up in server logs, browser history and referrer headers. Send the key in a request body, or in a header such as X-License-Key for the releases endpoint.
Why does a license check return HTTP 200 for an expired license?
Because the key is known and the request worked. The answer is in the body. Read the valid field, not only the status code.