Documentation

KeyGrant adds license keys, device activation, offline validation, trials and Stripe or Paddle sales to your app, on desktop and on phones. Integrate with a KeyGrant SDK, or call the REST API directly.

New to the terms? The Glossary defines each in a sentence or two.

Find what you need

How it fits together

1. Product

   Each app you ship. It has its own signing keypair, a key prefix, and an API ID, which every request from your app includes.

   Example: API ID my-product, key prefix MYPROD

   A product sells one or more license models.

2. License model

   One thing you sell, such as an edition at a given term and price. It sets its keys' type, device limit, Offline days, versions and entitlements. See License models.

   Example: Pro: perpetual, 3 devices

   Each sale, or each key you issue, under a model makes a license.

3. License

   A license key. It starts with its model's terms as they were when the key was created; its device limit, versions and entitlements can then be changed on that key alone.

   Example: MYPROD-9K4T-2M8P-XQ7V-H3DW

   A license activates on devices, up to its device limit.

4. Activation

   A key in use on one device. Each activation holds one of the key's seats, up to the key's device limit.

   Example: One laptop, holding 1 of the key's 3 seats

• API ID: made from the product's name when you create it, adding -2, -3 and so on when that ID is already in use on KeyGrant. It never changes.
• Key format: the product's key prefix, then four groups that never use the easily confused characters 0, O, 1 and I. Imported keys keep their original strings.
• A key with only a type: sold or issued with no model, it takes its device limit, grace period, entitlements and Offline days from the product's oldest model of that type.
• A lowered limit: lowering a key's device limit below its activations releases none of them; the key holds more until enough are released (see Change one key's limit).

Signed leases

When your app activates a key, and each time it checks in, KeyGrant returns a lease: a standard JWT, signed with EdDSA over Ed25519. Your app verifies it offline against the product's public key. A lease carries:

• the key, the product, the activation and the device;
• the versions it covers, its entitlements and its device limit;
• its expiry.

The app contacts KeyGrant again mainly when the lease is near its end or no longer licenses the app (see When the SDK goes online).

A lease lasts for the license model's Offline days, so if KeyGrant cannot be reached (during an outage, or when the device loses its connection), a paying customer's app keeps working until its lease runs out. Licensing fails in favor of the paying customer.

Because the lease is a standard JWT, any language can verify it with a JWT library that supports EdDSA, plus a few checks on KeyGrant's own claims (see Lease format). An SDK does all of this for you.

Ways to integrate

• An SDK: @keygrant/electron for Electron and Node, and SDKs for .NET, Rust, Swift, C++ and Flutter (iOS, Android and desktop) that share the same calls. See SDKs.
• The REST API: the client endpoints your app calls, and the server endpoints your backend calls with a secret key.
• Stripe: link your Stripe account and map prices to license models. Each paid checkout then creates a key, or upgrades the key the buyer already holds, with no code on your side. See Selling through Stripe.
• Paddle: link your Paddle account with an API key, map prices to license models, and pass the checkout's client_reference_id from a page of yours. See Selling through Paddle.