License Keys
How Keymint license keys work: key anatomy, creation, activation, node locking, seat limits, offline signing, and the full license lifecycle.
A license key is the credential that grants a customer access to your software. In Keymint, a key is issued for a specific product, configured with a seat limit, and enforced through machine-bound activations. This page explains everything about keys — from how they are created to how they are revoked.
Key Anatomy
A Keymint license key looks like this:
A8E2K-9F1BC-3D4GH-7J2KMKeys are generated server-side and globally unique. The key itself is a claim token — the actual entitlement lives on Keymint's servers, so copying a key to another machine does not grant access unless a free seat is activated on it.
Creating a License Key
Keys are created in the Dashboard or through the API with an admin-scoped key. When creating a key you specify:
- The product the key is valid for. A key is always bound to exactly one product.
- The seat limit (
maxActivations) — the maximum number of device activations: a whole number from 0 to 1,000,000 (as a number or a string), or"unlimited". Omitted ornullmeans unlimited. A limit of1produces a classic single-device license; higher limits allow the key to be activated on multiple machines. - An optional expiration (
expiryDate) for time-limited licenses (trials, rentals, or annual subscriptions). - Optional feature flags and metadata: features are predefined on the product, toggled per key, and delivered to your application inside
metadata.featureson activation. Arbitrary key/valuemetadata(e.g. tier) is also supported.
POST /key HTTP/1.1
Host: api.keymint.dev
Authorization: Bearer YOUR_ADMIN_API_KEY
Content-Type: application/json
{
"productId": "YOUR_PRODUCT_ID",
"maxActivations": "3",
"expiryDate": "2027-08-01T00:00:00Z",
"metadata": {
"tier": "premium"
}
}See the Create License Key reference for the full request schema.
Activation and Node Locking
Activation binds a key to a device. Your application sends the key plus a stable device identifier (hostId, 1–64 characters). The SDKs' installation ID (getOrCreateInstallationId) is the recommended value: a generated ID, anchored to the hardware where possible and stored on the machine. See Node-Locking & Machine Identifiers.
{
"productId": "YOUR_PRODUCT_ID",
"licenseKey": "A8E2K-9F1BC-3D4GH-7J2KM",
"hostId": "mac-studio-m2"
}Keymint records the activation and returns the license metadata (including the recorded hostId), the license expirationDate (or null) and, when a customer is assigned, their masked name and email. Subsequent activations on the same machine are idempotent; activations beyond the seat limit are rejected.
For production systems, call GET /key at launch from a trusted server to re-validate the activation and check for revocation (this endpoint requires a read-only or admin key — distributed apps should validate via activation instead). See Get Key Info.
License Lifecycle
A key moves through a well-defined set of states:
| State | Meaning |
|---|---|
| Active | Key is valid and activations are allowed. |
| Suspended / Blocked | Key is invalid. Activations fail and existing activations no longer validate. Useful for non-payment or abuse. |
| Expired | Time-limited key has passed its expiration date. |
| Deactivated | A seat was released by the user (for example, when the customer moves to a new machine). |
Operations that change state: Activate, Deactivate, Block, Unblock, and Update.
Floating Seats
For teams that share a pool of devices, keys can be created as floating licenses (licenseType: "floating"). Floating keys do not use permanent activations: applications check out a session, hold it with periodic heartbeats, and release it with check-in or automatically when the lease expires. Concurrency is capped by maxConcurrentSessions, with heartbeatInterval and sessionLeaseDuration controlling the lease. See Floating Licenses for the full architecture.
Offline and Signed Licenses
For air-gapped or high-security environments, Keymint can sign a license for a specific machine and issue a .lic file. The file contains an Ed25519-signed JWT with an expiry (TTL) that your application verifies locally with a bundled public key — no network connection required at runtime. Signing through the API needs an admin key or a key with the license:sign grant, and is available on every plan, including Free. See Offline Verification and the Sign License reference.
Best Practices
- Never trust client-side checks alone. Always validate against the API (or against the Ed25519 signature for offline licenses) on code paths that matter.
- Scope your API keys.
clientkeys can only activate/deactivate devices and run floating sessions; key management and reads requireread-only/adminkeys, which should stay server-side. - Use feature flags for tiering. Predefine features on the product, toggle them per key, and gate functionality in your app based on the
metadata.featuresmap returned by activation and checkout. - Plan for rejected activations. An expired, blocked, or unknown license, or a device not in
allowedHosts, returns HTTP 401 (code: 1) — deliberately the same response for all of them. A full license returns HTTP 403 withcode: 2. If your own Keymint subscription lapses with usage over the Free limits, new devices get HTTP 402 during a 30-day continuity period (devices already activated keep working), and every activation gets 402 after it. Map these to clear user-facing messages with a recovery path, and don't lock users out on network errors or 5xx responses. See Error Codes. - Match machine fingerprints carefully. Overly strict fingerprints (every hardware change) produce false revocations; overly loose ones weaken node locking.