The macOS Licensing Glossary: 25 Terms for Mac Developers

Every licensing guide assumes you already know the vocabulary. This one builds it. The terms below are organized by area — key concepts first, then activation mechanics, then payment lifecycle, then SDK runtime — so you can read the section most relevant to your current integration stage. Each entry links out to a deeper post when one exists.

License key concepts

License key. The string a customer pastes to register their copy of the app. In Keylight, the key is the public handle for an underlying signed lease — short, copy-pasteable, and the same shape every time. Read more.

Signed lease. A small structured document that carries a customer’s entitlements and is signed so that no field can be altered without breaking the signature. The app verifies the lease locally on every launch using the embedded public key — no server call required. Read more.

Ed25519. The public-key signature algorithm Keylight uses to sign leases. It is a signature algorithm, not an encryption scheme — its job is to prove that Keylight’s server produced this specific document, not to hide the contents. Ed25519 signatures are ~88 bytes and fast to verify, which matters for a check that runs on every app launch. Read more.

Private key. The secret half of the Ed25519 key pair, held on Keylight’s servers and never exposed. Only the holder of the private key can produce a signature the matching public key accepts — which is why an attacker who extracts the public key from your app binary still cannot mint a valid lease. Read more.

Public key. The verification half of the Ed25519 key pair, embedded in every copy of your app at build time. Safe to ship to the world: the public key verifies signatures but cannot generate them. Read more.

Key prefix. The short string prepended to every license key for a given product (for example, ACME-XXXXX-XXXXX). It makes keys visually recognizable as belonging to your product and is configured once in the Keylight dashboard. Read more.

Activation and devices

Activation. The first-time registration of a device against a license key, which consumes one slot of the activation limit. Activation requires a network call to the Keylight API and returns a signed lease the SDK stores in the Keychain. Subsequent launches verify the cached lease locally without re-activating. Read more.

Deactivation. The removal of a device from a license key’s activation list, freeing that slot for use on another machine. Customers can deactivate their own devices through the Keylight customer portal without contacting the developer. Read more.

Activation limit. The maximum number of concurrent device activations a license key allows. The limit is set per product tier at issuance and encoded in the signed lease — it cannot be changed by the customer. Exceeding the limit is rejected server-side at the /activate endpoint, not by the local verifier. Read more.

Instance ID. A stable, anonymous identifier generated by the Keylight SDK for each device. It identifies the machine to the server during activation and revalidation without sending hardware serials or personally identifiable information. Read more.

Device fingerprint. A derived identifier used to detect whether the same physical machine is trying to activate the same key from different identities — one of the server-side signals Keylight uses to detect license key sharing. Unlike the instance ID (which is app-scoped), a device fingerprint may draw on multiple hardware attributes. Read more.

License key sharing. The abuse pattern where a paying customer distributes their key to others outside the activation limit. Signed leases reduce the damage: editing the lease breaks the signature, so sharing requires distributing the key itself and each sharer consuming an activation slot. Read more.

Payments and lifecycle

Stripe Checkout. The hosted payment page Stripe provides for one-time purchases and subscription sign-ups. When a customer completes a Stripe Checkout session, Stripe fires a webhook event that Keylight consumes to mint and deliver a signed license. Read more.

Webhook. An HTTP POST request Stripe sends to Keylight’s endpoint when a payment event occurs — purchase, renewal, refund, or chargeback. Keylight verifies the Stripe-Signature header before trusting the payload, then mints or revokes the relevant lease. See Idempotency below. Read more.

Idempotency. The property that delivering the same Stripe webhook event twice produces the same outcome — one license key, one email — rather than duplicates. Keylight deduplicates on the Checkout session ID, so Stripe’s retry behavior cannot create duplicate keys for a single purchase. Read more.

Subscription. A recurring-payment license model where the signed lease carries an expiresAt tied to the Stripe billing period. Renewals re-mint the lease automatically; cancellations let it lapse at period end without requiring explicit revocation. Read more.

Trial. A time-bound evaluation window tracked on-device by the SDK. During the trial, the app runs with paid-tier features enabled. When the window closes, the SDK resolves to .freeTier (if configured) or .expired, driving the conversion prompt. Trial duration is a required parameter at SDK initialization. Read more.

Free tier. A keyless, persistent free-plan state the SDK resolves to after a trial expires when freeTierEnabled: true is set. A free-tier user has no license key and no activation — the SDK tracks them by the SDK’s instance ID for analytics purposes. The free tier is a distinct product state, not a trial with an infinite clock. Read more.

Revocation. The act of flipping the revoked flag server-side on a customer’s lease, typically triggered by a refund or chargeback processed through Stripe. The app picks up the revocation on the next online revalidation — offline use with a cached lease continues until that revalidation happens. This is the honest tradeoff of offline-first verification. Read more.

SDK and runtime

LicenseProvider. A Swift protocol that abstracts the licensing backend behind a uniform interface — trial lookup, activation, validation, cached-lease access, deactivation. The SDK ships two implementations: KeylightProvider (networked, Keychain-backed, with Ed25519 lease verification) and StoreKitProvider (App Store IAP-backed). Read more.

LicenseManager / state machine. The top-level object your SwiftUI app holds as a @StateObject. It exposes manager.state as one of six LicenseState cases — .trial, .licensed, .limited, .freeTier, .expired, .invalid — and drives your UI from that single source of truth. checkOnLaunch() resolves state from the Keychain immediately; refreshIfNeeded() handles background revalidation. Read more.

Offline lease. The cached, locally verifiable signed lease the SDK stores in the Keychain after activation. Because the Ed25519 signature covers the entitlements and expiry, the app can check the lease’s validity without a network round-trip on every launch — only the periodic background revalidation needs the network. Read more.

Keychain storage. The macOS system-level credential store the Keylight SDK uses to persist the signed lease across app launches, reinstalls, and auto-updates. Unlike UserDefaults or bundle-local files, Keychain items are scoped to the signing identity rather than the file path — which means the cached lease survives when an updater replaces the .app bundle. Read more.

Sandbox compatibility. The Keylight SDK works in sandboxed Mac apps without additional entitlements beyond the standard sandbox + com.apple.security.network.client. The SDK uses standard Keychain Services (not the Data Protection Keychain) on macOS; cross-app keychain sharing via keychain-access-groups is only required if multiple bundle IDs need to share a lease. Read more.

Auto-update persistence. The guarantee that a customer’s signed lease remains available after an auto-updater like Sparkle replaces the .app bundle. Because the lease is stored in the Keychain by service and account attributes — not by bundle path — the updated binary reads the same Keychain item the old binary wrote, with no migration step required. Read more.

---

This glossary is the index for the rest of the blog. Each entry points to the post that goes deeper, and those posts point to each other across the concepts they share. If a term you expected to find here is missing, send us your feedback and we will add it.