Migrating from a Homegrown Licensing System

This page is for developers who built their own licensing system — key generation, a license server, activation — and are finding that maintaining it takes more time than they want to spend. Rolling your own is a legitimate choice early on; it becomes expensive when the system is no longer simple. This guide covers when that threshold tends to arrive and what a migration to a managed system looks like in practice.

Why teams outgrow a homegrown licensing system

A self-built licensing system usually starts as a weekend project: generate a key string, store it in a database, check it on launch. That is enough to ship. Over time, the surface area grows — someone asks for offline support, so you add signing. Usage picks up, so activation limits become necessary. A refund happens, so you need revocation. Customers ask where to find their key, so a portal becomes a ticket-reduction project.

Each of those additions is reasonable in isolation. Together they form infrastructure: a service that needs to stay up, a signing key that needs to be kept secure, an API that needs to handle edge cases correctly, and a portal that needs to match the rest of your product. None of it is the app you are trying to build. When the incremental cost of keeping the licensing system current exceeds what it would cost to replace it, the math has shifted.

What a DIY setup has to get right

The technically demanding parts of a licensing system are concentrated in four areas.

Cryptographic key signing. A key that a determined user can mint themselves is not an effective key. Proper signing requires a private key the app never sees, a signature scheme the app can verify without trusting the user’s machine, and a plan for rotating keys if the signing key is ever compromised. This is the part most software license keys explanations skip over, and the part homegrown systems most often get wrong — using symmetric secrets in the app binary, or skipping signing entirely.

Offline verification. A system that requires a server call on every launch can be bypassed by blocking the server, and it fails for customers who are on a plane or behind a corporate firewall. Offline verification means the app can validate a signed lease (the cryptographically signed document Keylight returns at activation and stores locally on the device) it received at activation time without contacting the server on subsequent launches. Getting this right requires understanding how an app activation system works — specifically the interaction between the initial online activation and the signed document the app stores locally.

Device activation limits. Enforcing a per-device limit requires idempotent activation records on the server — re-activating a known device must not consume a new slot. Homegrown setups often skip this entirely, or implement it in a way that breaks when customers reinstall their OS.

Revocation. A refunded or disputed sale should stop working. Revocation requires the server to refuse activation for a revoked key, and the local signed lease to expire so the app does not run indefinitely offline after revocation.

Migrating self-issued keys and customers

The main migration task for existing customers is bringing them into Keylight. The process is one upload: export your customer list from whatever database backs your current system, then use Licenses → Import in Keylight to import it as a CSV. Include each customer’s existing key to preserve it — they keep the key they already have — or leave it blank and Keylight generates a signed license key. Every imported license is tagged Migrated, and Keylight stores the customer record and the activation limit you assign. See the full migration guide for the complete process.

Customers who kept their existing key need nothing from you — that key already works in the Keylight build. You only email customers whose key was generated during import; for them, a short message with the new key (and that they will enter it next launch) is enough. Either way, no one is asked to repurchase.

During the cutover, run your old server in read-only mode: it can still validate existing keys but should not issue new ones. New purchases go through Keylight from the moment you switch — routed through your own Stripe account so payments stay under your control. Once the queue of existing customers has activated their new keys and the old server is no longer receiving meaningful traffic, you decommission it.

The migration process, step by step

1. Connect your Stripe account to Keylight. Stripe is used for new purchases going forward — a completed payment triggers Keylight to mint and deliver a signed key automatically.
2. Recreate your products as Stripe prices in Keylight. Match the tiers you sold previously: personal, team, or whatever variants you offered. Set activation limits per tier to reflect what customers originally purchased.
3. Import existing customers into Keylight. For each customer, record the product tier they purchased and the activation limit they are entitled to.
4. Import your existing customers from Licenses → Import — include their current key to preserve it, or leave it blank to generate one. A one-time upload; customers who kept their key need no email.
5. Point the app’s activation at the Keylight SDK. The SDK handles device fingerprinting, the activation request, and local storage of the signed lease. Offline license validation works automatically after the first online activation.
6. Run the old server read-only during the transition window for any in-flight orders or support cases, then shut it down once traffic has moved.

Doing it with Keylight

Keylight replaces the entire DIY stack — cryptographic key signing, the activation server, idempotency, revocation, and a customer portal — as a managed service. There is no signing key to rotate, no activation API to scale, and no portal to build. Device activations are enforced server-side with idempotent handling built in: re-activating a known device never consumes a new slot, and customers deactivate old devices themselves without involving you.

On the app side, the Swift SDK reduces activation to a single call:

import KeylightSDK

// Activate a customer-entered key on this device
await licensing.activate(key: enteredKey)

switch licensing.state {
case .licensed:
    enablePaidFeatures()
case .invalid:
    // activationError carries the reason — e.g. activation limit reached
    showActivationError(licensing.activationError)
default:
    break
}

After activation, the SDK stores a signed lease the app verifies locally on every subsequent launch — no server call needed for day-to-day validation. The device activation count is tracked on the server, which stays the source of truth: you see how many devices a key is using from the Keylight dashboard.

Pricing starts at $19/month with a free tier that covers the complete flow — key issuance, activation, and offline verification — so you can validate the migration against your app before going live with customers.