How it works
A license answers one question: did this person buy? An entitlement answers the next: what do they get? A sale can grant a product, a tier, a version range, a number of devices and a period. The app reads those facts from the license and maps them to behaviour. How that mapping is stored decides whether it can be forged. A value in a local settings file can be edited. A value inside a signed token cannot, without the seller’s private key.
What Clavem carries
Clavem has no entitlement list and no feature-flag field. The entitlement is spread over a few fields, and only some are signed. This is the real payload of the public demo license’s token:
{ "v": 1, "lid": 1, "pid": 1, "kh": "7e0e4148136b6dae", "status": "active",
"valid": true, "email": "ada@example.com", "iat": 1795126842, "refresh_by": 1796336442 }
| Part of the entitlement | Field | In the signed token |
|---|---|---|
| Product | pid |
Yes |
| Valid now | valid, status |
Yes |
| Until when | exp, absent when perpetual |
Yes |
| Device count | activation_limit |
No, API response only |
| Variant name | meta.variant_name |
No, API response only |
The last two are in the validate response, but nothing signs them. An app that trusts them offline trusts a file the customer can edit.
A worked mapping
Each tier becomes its own Clavem product, so the signed pid says which tier the customer bought. An example with made-up prices and ids:
| Stripe price | Clavem product | Validity | Device limit | The app turns on |
|---|---|---|---|---|
| $29 one-time | Inkwell Basic, pid 75 | Perpetual | 1 | Editor, PNG export |
| $59 one-time | Inkwell Pro, pid 76 | Perpetual | 3 | Basic, plus PDF export and sync |
| $5 a month | Inkwell Pro Monthly, pid 77 | Follows subscription | 3 | Same as Pro while paid |
In Clavem you map a Stripe price to a Clavem product, and a mapping to one price wins over a mapping to its whole Stripe product. Each product has its own Ed25519 key pair, and a token from one does not verify against another’s public key, so the app tries each public key:
const TIERS = [
{ name: 'basic', pid: 75, publicKey: BASIC_PUBLIC_KEY },
{ name: 'pro', pid: 76, publicKey: PRO_PUBLIC_KEY },
];
async function tierOf(token) {
for (const t of TIERS) {
const claims = await verifyToken(token, t.publicKey);
if (claims && isLicensed(claims, t.pid)) return t.name;
}
return 'free';
}
verifyToken and isLicensed are on the offline verification page. This code ran against tokens signed with two test keys: a token from the second key came back pro, and a malformed token came back free.
Entitlement versus license
Keep the two apart when you design. If you want an upgrade from Basic to Pro, the customer needs a Pro license, not an edit to the Basic one, because the product, and therefore the signing key, is different. A signed token proves a license. Your mapping decides the entitlement.
How Clavem handles it
Clavem issues the license, enforces the device limit and expiry, and signs the answer. It does not store features. Changing a device limit or expiry on one license is a PATCH in the API reference, as in a goodwill extension. See license expiry and device limit.
Questions
What is the difference between a license and an entitlement?
The license is the record that a purchase happened, identified by a key. The entitlement is what that record grants. Two licenses can have different entitlements, for example a Basic and a Pro purchase.
Where should feature checks read the entitlement from?
From data your app can trust. A signed token can be trusted offline. An unsigned API response is fine for showing information but should not be the only thing that turns paid features on.