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-7J2KM

Keys 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, passed as a string) — the maximum number of device activations. A limit of "1" produces 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.features on activation. Arbitrary key/value metadata (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": "prod_Nx8K2mLpQ4rVtW9sBc",
  "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 unique hardware identifier (hostId) — typically a fingerprint derived from BIOS, CPU, and disk serials, or a generated ID stored on the machine:

{
  "productId": "prod_Nx8K2mLpQ4rVtW9sBc",
  "licenseKey": "A8E2K-9F1BC-3D4GH-7J2KM",
  "hostId": "mac-studio-m2"
}

Keymint records the activation and returns the seat owner, the license metadata, and the allowed hosts. 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:

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 that your application verifies locally with a bundled public key — no network connection required at runtime. 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. client keys can only activate/deactivate devices and run floating sessions; key management and reads require read-only/admin keys, 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.features map returned by activation and checkout.
• Plan for rejected activations. Activation failures return HTTP 403 with code: 2 when the license is expired, blocked, or the activation limit is reached, and code: 3 when the device is not in allowedHosts — map these to clear user-facing messages with a recovery path.
• Match machine fingerprints carefully. Overly strict fingerprints (every hardware change) produce false revocations; overly loose ones weaken node locking.