License every version from one key pair
Rotating your signing keys for each major version is the trap: it breaks older builds, forces a mass migration, and gives you no per-customer control. The better model keeps one key pair for the life of the product and carries what a license may do — which versions it runs, which features it unlocks, how much it may use — in signed entitlements. This post shows the three patterns with real code, how the grants stay tamper-proof online and offline, and when to reach for full release coverage instead.
There is a tempting shortcut when you ship a new major version of a paid product: issue the new version’s licenses under a new signing key pair, embed the new public key in the new build, and let the old keys stop verifying. It looks like a clean break. It is a trap.
A key pair tied to a version breaks everything older — a 3.x build cannot verify a license signed under the 4.x key, and vice versa. You are forced to re-issue and migrate every paying customer at once, on your schedule, not theirs. And you get no granularity: you cannot let one customer’s license cover both 3.x and 4.x, because the key is all-or-nothing. The key pair is the wrong place to encode a commercial decision.
The model: one key pair, for the life of the product
Keep one signing key pair for the product forever. The public key embedded in your app never moves — shipping 4.0 does not touch it. Carry what a license may do in entitlements: signed name → value grants that ride inside the license and are verified against the key you already embed.
Change what a customer may run, unlock, or use by re-issuing their key — never by rotating keys and shipping a new public key.
An entitlement is delivered two ways your app already verifies: inside the offline license file, and inside the short-lived online activation lease. Both are RSA-signed and checked against your embedded public key, so a customer cannot add a grant, flip a flag, or raise a number — editing any of it breaks the signature and the SDK refuses the whole artifact. Because every SDK (.NET, Node, Python, Java) and the raw HTTP format verify the identical signed payload, the same grants read the same way across a mixed-language product line from one public key.
Case 1 — version enforcement, without rotating keys
Your app knows its own major version. The license carries the highest major it covers. Run only at or below that ceiling:
const int runningMajor = 4; // this build's major version
var raw = info.Entitlements.GetRaw("max_major_version"); // e.g. "3" or "4" (a name you choose)
int ceiling = int.TryParse(raw, out var m) ? m : 3; // absent => your pre-coverage default
if (runningMajor > ceiling)
ShowUpgradeRequired($"Your license covers up to v{ceiling}.x.");
A license sold for the 3.x line carries max_major_version: "3" — or nothing, if it predates the scheme, in which case your code treats “absent” as the last major before you added the rule. Ship 4.0 and it declines that key locally, against the public key already in the app. A customer who buys the 4.0 upgrade gets their key re-issued with "4". A higher ceiling still runs on older builds, so a 4.x license keeps working on 3.x. No key moved; no build shipped a new public key.
Case 2 — unlock a feature
A boolean grant — on or off. The accessor treats true, 1, yes or enabled as on:
if (info.Entitlements.IsEnabled("feature.pdf_export"))
EnablePdfExport();
This is the per-edition unlock: “Export”, “SSO”, “advanced reports” switch on from the customer’s license, verified offline, and you change who gets what by re-issuing — no new build. (Operational feature flags for a rollout you control layer inside what the entitlement already allows; the entitlement is always the hard gate.)
Case 3 — enforce a numeric quota
A number the customer paid for — seats, projects, API calls, devices. The limit read treats "unlimited" as effectively infinite, and the fallback is what a missing value gets (fail closed):
long maxProjects = info.Entitlements.GetLimit("max_projects", fallback: 3);
if (currentProjectCount >= maxProjects)
throw new QuotaExceeded($"Your plan allows {maxProjects} projects.");
Raising a customer’s limit is a key re-issue with a new max_projects. No build, no key change, and it takes effect on their next lease renewal or next offline license.
Setting the grants
Attach entitlements when you issue or update a key — dashboard, or the admin API:
curl -X POST "https://keyright.example.com/admin/licenses" \
-H "X-Admin-Token: $KEYRIGHT_ADMIN_TOKEN" -H "Content-Type: application/json" \
-d '{ "licensee": "Acme Ltd", "product": "your-product", "tier": "pro",
"entitlements": { "max_major_version": "3", "feature.pdf_export": "true", "max_projects": "10" } }'
Better still, put the defaults on the edition/tier template so every key issued under it inherits them. That is how “automatic going forward” works: set max_major_version on your current edition today, and when you ship the next major, bump the template (or add a new edition). Every key minted afterward carries the new ceiling; every key already in the field keeps whatever it was issued with, and keeps working.
When to reach for release coverage instead
A plain max_major_version entitlement answers “which versions may this license run” at the granularity of a major. If you sell by release date, maintenance windows, or exact version ranges — “every 2.x release”, “anything shipped in the year after purchase”, “whatever ships while the subscription is active” — use Keyright’s first-class release coverage, which records and signs the full coverage set and answers eligibility for any specific build. The entitlement is the lightweight, major-grained version of the same idea; release coverage is the precise one.
The takeaway
Your signing key pair identifies your product, not a version of it. Keep it stable for the life of the product and let signed entitlements carry the commercial decisions — which versions a license runs, which features it unlocks, how much it may use. You change what a customer may do by re-issuing their key against the key you already ship, and older builds never break because the public key never moved.
Try Nebula.NET
Harden your .NET code in minutes — start with the free edition.