License entitlements vs. feature flags
A feature flag is an operational switch you control; a license entitlement is a signed commercial grant the customer paid for. Confuse them and a customer flips a flag to unlock what they never bought. This post draws the line, shows the failure modes of using the wrong tool, gives a decision table, and wires the combined Keyright architecture: entitlements as the hard gate, feature flags layered on top for rollout within what a customer is entitled to.
Reach for a feature-flag system to gate a paid feature and the code looks right the first day. flags.IsEnabled("advanced-reports") wraps the export button, the toggle is off for free users and on for paying ones, and the demo works. Then a customer opens the flag store you handed them, flips the toggle, and gets a feature they never bought — or your rollout service has a bad afternoon, the client falls back to its default, and every install either over- or under-unlocks at once. Nothing was hacked. The tool was simply the wrong one: a feature flag is an operational switch, and you used it to draw a commercial boundary.
This post draws the line between the two, shows what breaks when you cross it, and then wires them together the right way in a Keyright-licensed .NET app — entitlements as the hard gate, flags layered on top for rollout within what a customer is entitled to.
Two tools that look alike and aren’t
Both answer a yes/no question about whether a capability should run, so they’re easy to conflate. The difference is in who controls the answer and whether the answer is trustworthy.
A feature flag is a mutable toggle that you control. You set it, you change it, you roll it out to 5% of accounts and then to everyone, you kill it when an experiment ends. It’s an operations and delivery mechanism. It has no cryptographic integrity because it doesn’t need any — the party reading the flag (your app) and the party setting it (you) are on the same side.
A license entitlement is a signed, tamper-evident grant tied to what the customer paid for. The customer holds the license; you hold the private key that signed it. The app verifies the signature against an embedded public key, so the entitlement set cannot be forged or edited by the party it restricts. It’s a commercial boundary, and its whole value is that the person on the other side of it cannot flip it themselves.
Failure mode 1 — flags for licensing
Gate a paid capability with a flag and you inherit three problems at once.
It’s trivially bypassed. Whatever stores the flag — a config file, a local database, a cache the SDK writes to disk — is reachable by the customer. There’s no signature over it, so editing it has no detectable consequence. The “boundary” is a boolean the restricted party can set to true.
There’s no offline story. A hosted flag service answers over the network; when it can’t be reached, the client serves a default. A default is a fine answer to “should this experiment be on?” and a terrible answer to “did this customer buy this?” You end up choosing between failing open (giving away paid features during an outage) and failing closed (breaking features your customer legitimately paid for because your service blinked).
There’s no integrity, so there’s no audit. When a dispute arises over what a customer was entitled to, a signed license is evidence: it says what was granted, by whom, until when, and the signature proves it wasn’t altered. A flag value is just a row someone could have written.
Failure mode 2 — entitlements for a staged rollout
The reverse mistake is subtler. Suppose you ship a new report engine and you want to turn it on for 5% of entitled customers on Monday, 50% on Wednesday, everyone on Friday — classic rollout. If you model that with the entitlement, every dial change is a re-issue: a new signed license, a trip through your commercial pipeline, a re-activation on the customer’s side. Entitlements are deliberately expensive to change because they represent money; that cost is exactly wrong for an operational knob you want to turn three times a week. You’d also be minting commercial grants for a decision that has nothing to do with what anyone paid — polluting the thing whose entire value is that it only reflects purchase.
The decision table
| Dimension | Feature flag | License entitlement |
|---|---|---|
| Integrity | None — a mutable value, no signature | Cryptographically signed, tamper-evident |
| Who controls it | You (vendor), at runtime | Granted by you, held by the customer, verified by the app |
| Offline behavior | Falls back to a default; often needs the network | Validated locally against the embedded public key; fails closed |
| Change latency | Seconds — flip and it’s live | A re-issue: new signature, re-activation |
| Audience | A cohort you choose (percentage, ring, account) | The specific customer and what they purchased |
| Right job | Rollout, experiments, kill switches, ops toggles | Commercial boundaries: editions, seat caps, paid capabilities |
Read the table as a single rule: if the answer must survive the customer being adversarial and the network being down, it’s an entitlement; if you need to change it quickly and you’re the only one who should, it’s a flag.
Entitlements in Keyright
A Keyright entitlement is read from a locally validated license. You initialize the client once with your product name and verify-only public key, then validate — offline, against the embedded key.
using Keyright;
static readonly KeyrightClient License = KeyrightClient.Initialize(new KeyrightOptions
{
Product = "acme-analytics",
PublicKeyBase64 = "MIIBIjANBgkq...", // verify-only; ships in the binary
ServiceUrl = "https://keyright.example.com", // only needed to activate online
});
// Local, no network: verifies signature, expiry, node-lock and the entitlement set.
// Never throws for license state; fails closed to Community Edition.
LicenseInfo info = await License.ValidateAsync();
bool canExport = info.Entitlements.IsEnabled("advanced-reports");
info.Entitlements is the signed set the customer paid for. IsEnabled is a pure local read — no round-trip — and because validation fails closed, a missing, expired, or tampered license resolves to Community Edition with the entitlement reading false. That is the hard gate: the capability is unavailable unless the signed grant says otherwise, and nothing the customer can edit changes that answer.
Composing a flag with an entitlement
Now the real architecture: the two tools layered, not substituted. The entitlement decides whether this customer may ever have the capability; the flag decides whether we’ve turned it on yet for them. The order is not negotiable — the entitlement gates, the flag only narrows.
public sealed class ReportService
{
private readonly IFeatureFlags _flags; // your rollout system (OpenFeature, homegrown…)
public ReportService(IFeatureFlags flags) => _flags = flags;
public async Task<IActionResult> RunAdvancedReport(ReportRequest req)
{
LicenseInfo info = await License.ValidateAsync();
// 1. Hard gate: did the customer PAY for this capability? Signed, offline, fail-closed.
if (!info.Entitlements.IsEnabled("advanced-reports"))
return Forbid("advanced-reports is not part of your plan");
// 2. Rollout narrowing: is the new engine turned on for this account yet?
// This can only withhold a paid feature during rollout — never grant an unpaid one.
if (!_flags.IsEnabled("advanced-reports-v2-rollout"))
return await RunLegacyReport(req);
return await RunReportV2(req);
}
}
Read the two checks. The entitlement check is load-bearing: remove it and any account reaches the feature. The flag check is narrowing: remove it and entitled customers simply all get v2 at once — a rollout decision, never a security one. Because the flag sits inside the entitlement’s success branch, it is structurally impossible for a flag to unlock an unpaid capability. The worst a misconfigured flag can do is keep a paying customer on the legacy path for a while.
The same composition expresses a staged rollout of a brand-new paid capability. Entitle it the moment it’s sold, then gate the actual turn-on behind a percentage flag so you control the blast radius — without ever letting the flag become the thing that decides whether the customer bought it.
if (info.Entitlements.IsEnabled("live-collaboration")
&& _flags.IsEnabled("collab-ga-rollout"))
{
EnableCollaboration();
}
The && reads left to right and that’s the whole design: entitlement first because it’s the commercial truth, flag second because it’s the operational knob. Flip the operands and you’ve rebuilt failure mode 1.
Where numeric limits fit
The same split applies to quantitative boundaries. A seat cap is commercial — it’s in the signed license — so it belongs to the entitlement side:
long maxSeats = info.Entitlements.GetLimit("max-seats", defaultValue: 1);
if (activeSeats >= maxSeats)
return Forbid("seat limit reached for your plan");
A flag might then control how you enforce an over-limit situation during a rollout — hard block versus grace banner — but the number itself, the thing tied to money, stays in the entitlement where it’s signed and offline-verifiable.
The rule, in one line
Gate what the customer paid for with a Keyright entitlement: signed, tamper-evident, verified offline, changed only by a deliberate re-issue. Gate how and when you roll that out with a feature flag: fast, yours, disposable. Keep the flag strictly inside the entitlement’s yes, and the two reinforce each other instead of one quietly undoing the other.
Try Nebula.NET
Harden your .NET code in minutes — start with the free edition.