Skip to content

Use cases

Entitlements

Entitlements are signed key/value grants carried inside every Keyright license and lease. Use them to enforce feature access, numeric quotas and which product versions a license runs — all from one signing key pair, so you ship a new major version by re-issuing a key, never by rotating keys and shipping a new public key.

Goal. Change what a customer may do — which features they get, how many of something they may use, and which versions of your product they may run — without shipping a new build, and without ever rotating your signing keys. Entitlements are the one mechanism underneath all three.

What an entitlement is

An entitlement is a name → value pair you attach to a license. Keyright signs it into the license with your tenant’s private key and delivers it to the customer’s machine two ways that your app already verifies:

  • inside the offline license file, and
  • inside the short-lived online activation lease.

Both are RSA-signed and checked against the public key embedded in your app, so a customer cannot add an entitlement, flip one on, or raise a number — editing any of it breaks the signature and the SDK refuses the whole thing. Nothing in an entitlement is secret; the security is the signature, not hiding the value.

Because every SDK (.NET, Node, Python, Java) and the raw HTTP format verify the identical signed payload, the same entitlements are readable the same way across a mixed-language product line from one public key.

The principle: one key pair, every version

The most common licensing mistake is tying the signing key pair to a product version — issuing 3.0 licenses under a new key and shipping a new public key in the 3.0 build. It breaks older builds (they can’t verify the new key), forces a migration of every paying customer at once, and gives you no per-customer control.

Keyright’s model is the opposite:

Keep one key pair for the life of the product. Carry what a license may do in signed entitlements, and change it by re-issuing the key — never by rotating keys.

The public key in your app never moves. Shipping 4.0 doesn’t touch it. Whether a given license may run 4.0 is an entitlement question, answered locally against the key you already embed.

The three patterns

Read entitlements off the resolved LicenseInfo. The .NET SDK exposes an EntitlementSet with typed accessors; the other SDKs expose the equivalent.

1. Feature flags — unlock a capability

A boolean grant: on or off. IsEnabled accepts true, 1, yes or enabled.

var info = client.Validate();                 // offline, from the cached lease/license
if (info.Entitlements.IsEnabled("feature.pdf_export"))
    EnablePdfExport();

This is the classic per-edition unlock. For the full treatment — defining features on an edition, the paid-vs-free gate, combining with operational feature flags — see Gate features & editions.

2. Numeric quotas — enforce a limit

A number the customer paid for: seats, projects, API calls, devices. GetLimit parses the value and treats "unlimited" as effectively infinite; the fallback is what an unlicensed or 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.");

Change a customer’s limit by re-issuing their key with a new max_projects — no build, no key change.

3. Version enforcement — which releases a license runs

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"
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.");

This is how you ship a new major without rotating keys: a license sold for the 3.x line carries max_major_version: "3" (or nothing, if it predates the scheme), so 4.0 declines it locally; a license that includes the 4.0 upgrade carries "4". A higher ceiling still runs on older builds, so a 4.x license keeps working on 3.x.

max_major_version is a name you choose. Pick any key your app agrees on. The value is a plain string; parse it however you version.

Need finer control than “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 engine, which records and signs the full coverage set and answers eligibility for any version. The entitlement above is the lightweight, major-grained version of the same idea; release coverage is the precise one.

Setting entitlements

On a single license

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": {
      "feature.pdf_export": "true",
      "max_projects": "10",
      "max_major_version": "3"
    }
  }'

In the dashboard they appear in the Features editor on the Issue-license dialog as key → value rows.

On an edition/tier template (inherited automatically)

Put the defaults on the edition so every key issued under it inherits them. This is how you make it automatic going forward: 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, and every key already in the field keeps whatever it was issued with.

curl -X POST "https://keyright.example.com/admin/products/your-product/tiers" \
  -H "X-Admin-Token: $KEYRIGHT_ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{ "name": "Pro", "seats": 3,
        "entitlements": { "feature.pdf_export": "true", "max_major_version": "3" } }'

How entitlements reach the app

issue/update license  ──signs──▶  offline license file   ─┐
         │                                                 ├─▶  your app verifies against the
         └──on activation──▶  signed online lease  ────────┘     embedded public key, reads EntitlementSet
  • Offline licenses carry the entitlements in the signed document; air-gapped machines read them with no network.
  • Online leases carry the same entitlements, signed at activation, so the online path exposes exactly what the offline path does. A lease renews against the service before it lapses — so re-issuing a customer’s entitlements takes effect on their next renewal, with no key re-entry and no reactivation.

Because the values are in the signed payload, a tampered or hand-edited file fails verification and is refused entirely — you never read a forged entitlement.

Reading entitlements in each SDK

Every SDK resolves the same signed set. The accessors (names may differ slightly) are: an IsEnabled(name) boolean check, a GetLimit(name, fallback) numeric read ("unlimited" ⇒ max), a raw string read, and a list/membership helper for multi-value grants.

  • .NET — info.Entitlements.IsEnabled(...), .GetLimit(...), .GetRaw(...), .GetList(...), .IsListed(name, value).
  • Node / Python / Java — the same reads on the resolved license’s entitlements.
  • HTTP — the entitlements are a JSON object on the signed lease/license; verify the signature, then read the object directly.

See the per-language guides under SDK integration, and the runnable samples repo (operation 7 demonstrates all three patterns).

Entitlement vs. feature flag vs. release coverage

You want to…Use
Unlock a capability a customer paid forEntitlement (boolean) — this page / gate features
Enforce a numeric limit (seats, projects, calls)Entitlement (GetLimit)
Gate a whole major version, simplyEntitlement (max_major_version)
Gate by release date / version range / maintenance windowRelease coverage
Stage a rollout you control (not a purchase)An operational feature flag, layered inside what the entitlement already allows

Verify

  1. Issue two keys under the same product and key pair — one with max_major_version: "3", one with "4".
  2. In a build whose major is 4, confirm the first is declined (“upgrade required”) and the second runs — with the same public key in the app.
  3. Edit a stored lease/license to raise max_projects or add feature.pdf_export; confirm the SDK rejects it (the signature no longer matches).
  4. Issue a key with no max_major_version; confirm it behaves as your documented pre-coverage default.