EYMINT
DocumentationAPI Reference
BlogDashboard
EYMINT
SectionsDocumentationAPI Reference
Go to Dashboard

For AI agents: the documentation index is at /llms.txt. Every docs page is also available as markdown by adding .md to its URL.

Getting Started

  • Keymint Documentation
  • Introduction
  • Getting Started
  • License Keys
  • Changelog

SDK References

  • Software Development Kits (SDKs)
  • Node.js SDK
  • Go SDK
  • Python SDK
  • C# SDK

Integration Guides

  • Integration Guides
  • Customer Portal for Vendors
  • Roles & Permissions
  • Radar Alert Destinations
  • Payment Provider Integrations
  • Stripe Subscription Licensing
  • Import Existing License Keys
  • Email Delivery
  • API Key Management
  • Webhook Deliveries
  • Analytics and Retention
  • Dashboard Workflows
  • Electron Licensing
  • PyQt Licensing
  • Tauri Licensing
  • Next.js SaaS Licensing

Licensing Guides

  • Licensing Concepts
  • Node-Locking & Machine Identifiers
  • Floating Licenses
  • Offline Verification
  • License Radar
  • Public Key Management and Rotation
  • Feature Flags
  • Webhooks & Events

Templates

  • Starter Templates
  • Electron License Starter
  • PyQt License Starter
  • Tauri License Starter
  • Next.js SaaS License Starter

Security & Trust

  • Security & Trust

Support

  • Frequently Asked Questions
  • Customer Portal
  • Using the Customer Portal
  • Workspace Settings and Roles

Legal

  • Privacy Policy
  • Subprocessors
  • Data Processing Agreement
  • Security Overview
  • Terms of Service
  • Service Level Agreement (SLA)
  • GDPR Compliance

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:

text
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) — the maximum number of device activations: a whole number from 0 to 1,000,000 (as a number or a string), or "unlimited". Omitted or null means unlimited. 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.
http
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.

json
{
  "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:

StateMeaning
ActiveKey is valid and activations are allowed.
Suspended / BlockedKey is invalid. Activations fail and existing activations no longer validate. Useful for non-payment or abuse.
ExpiredTime-limited key has passed its expiration date.
DeactivatedA 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. 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. 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 with code: 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.

Create a Key

POST /key — issue a new license key for a product.

Activate a Key

POST /key/activate — bind a key to a device.

Get Key Info

GET /key — read license status, metadata, and features.

Floating Licenses

Concurrent sessions with checkout, heartbeat, and check-in.

Offline Verification

Ed25519-signed license files for air-gapped machines.

License Key APIs

The complete License Keys endpoint reference.

On this page

  • Key Anatomy
  • Creating a License Key
  • Activation and Node Locking
  • License Lifecycle
  • Floating Seats
  • Offline and Signed Licenses
  • Best Practices