Migrate License Keys Without Breaking Existing Customers

The thing that stops developers from moving their licensing isn’t the work. It’s the fear of one specific moment: a paying customer opens the app after you’ve switched, and it tells them they’re unlicensed. That’s the nightmare — you reach for lower fees and customer ownership, and the bill comes due as a wave of “I already paid for this” support tickets.

It’s a reasonable fear, and it’s also avoidable. Migrating onto Keylight doesn’t require invalidating anything, re-issuing anything, or asking customers to do anything. This post is about the one rule that keeps everyone working, the two situations you might be in, and why a scary-sounding “major version” jump changes none of it. When you’re ready for the click-by-click mechanics, the companion piece covers them: How to Import an Existing Customer Base into Keylight.

Why migrating licensing feels risky

A license check is binary in the moment a customer experiences it: the app either lets them in or it doesn’t. So any change to the system behind that check feels like it’s playing with a live wire. Switch the layer that answers “is this person allowed in,” the thinking goes, and you risk every existing customer getting the wrong answer at once.

That instinct is right about the stakes and wrong about the mechanism. The wave of lockouts people picture comes from one specific mistake: treating migration as a cutover, where the old keys stop being recognized the instant the new system goes live. If your migration invalidates the old keys, yes — everyone breaks. The entire trick is to not do that.

The one rule: old keys stay valid

Here’s the rule the whole migration hangs on: you bring your customers’ keys in as they are, and nothing gets invalidated.

When you import an existing customer, their license is a live, active record from the first second. If you include the key string they already have, that key is what Keylight stores — not a replacement. So when your new build asks Keylight “is this key good,” the answer is yes, because it’s the same key, now on a system that recognizes it. The customer never repurchases and never loses access — though how that key first reaches Keylight (your app reads it, or the customer enters it once) deserves its own section, below.

This is also why running both systems in parallel for a little while is the safe play, not a hedge. Keep your old checkout and verification alive for a few weeks while customers drift onto the new build, then retire the old path once it’s quiet. There’s no single instant where everything has to flip. Migrations break when someone tries to flip everything at once; they’re uneventful when the old keys keep working the whole way through.

From your app’s side, an imported key needs no special handling. It resolves to the same state a freshly minted key would:

// Once a key has been activated once, an imported license validates exactly
// like one you minted by hand — there is no "migrated" branch in your launch
// logic. checkOnLaunch() reads the cached, locally-verified lease and maps it.
switch await licenseManager.checkOnLaunch() {
case .licensed:
    // The customer's existing key resolved to an active lease.
    // Show the full app. Imported or not, this looks identical.
    showMainWindow()
case .limited:
    // A lapsed subscription with fallback access — renew prompt, keep
    // export available. Not relevant to most one-time-license imports.
    showRenewBanner()
case .invalid:
    // No license stored, or verification failed. New users land here.
    showActivationSheet()
default:
    break
}

There’s no case .migrated. Provenance lives in your dashboard, not in your app’s control flow — the SDK has nothing to special-case, because an imported active license is an active license.

How your app picks up the existing key

This is the honest crux, and the question that decides whether the migration is invisible or merely painless: a customer who bought before Keylight existed has no Keylight lease on their machine — no Keychain entry, no signed token, nothing to find. The lease that proves entitlement gets created the first time their key is activated against Keylight. Import seeds the record on Keylight’s servers; it never reaches onto the customer’s device. So something has to hand the key to Keylight once. There are three ways, and they differ only in how much you do.

1. The customer enters their key once — you write no migration code. Ship your new build with the activation UI you already integrated (LicensePromptView). A returning customer who isn’t activated yet sees the prompt, pastes the key they already own, and it validates immediately — because you imported it. One paste, no purchase. This is the floor: it always works and costs you nothing.

2. Your app reads the old key and activates it silently — a few lines of your code. If your previous system stored the raw key somewhere your new build can read — UserDefaults, a plist, its own Keychain item — read it on first launch and call manager.activate(key:) yourself. The customer sees nothing at all:

// One-time migration shim. If this install has no Keylight license yet, read
// the key your OLD system stored and activate it. After this, the cached lease
// drives every launch.
if case .licensed = manager.licenseState {
    // already migrated — nothing to do
} else if let legacyKey = UserDefaults.standard.string(forKey: "licenseKey") {
    // ^ YOUR previous storage — NOT a KeylightSDK call. Swap in your own read
    //   (plist, a file, your old Keychain item). Only your app knows where the
    //   legacy key lived; the SDK can't, so there's no helper for this part.
    try? await manager.activate(key: legacyKey)   // ← this IS the SDK call
}

That UserDefaults read is a stand-in for your old storage — it is not a KeylightSDK call, and Keylight can’t ship one, because only you know where the key lived or whether it’s recoverable at all. The only SDK call here is manager.activate(key:). Two things have to be true for this path: the old key is readable on the device, and you imported with that same key string (the license_key column) so the server record matches. When they are, the migration is genuinely invisible.

3. Keylight’s hosted claim page — no app code at all. Turn on Claim a legacy key and customers prove ownership of their old key at a Keylight-hosted portal page; Keylight mints a license and emails it, white-labeled. You write nothing in the app. The tradeoff: it mints a fresh key rather than preserving the old string, and it’s customer-driven — a good fit for a frozen app whose key you can’t read anyway.

The takeaway for the nervous developer: none of this requires you to write code for the migration to work. Routes 1 and 3 are zero app code. You only reach for the shim in Route 2 when you want the customer to notice nothing whatsoever — and even then it’s a few lines against a key you’ve already preserved.

Two paths — pick yours

There are two situations a developer is usually in when they migrate, and they call for different moves. The good news is that both are safe; they’re just safe for different reasons.

Your old app can’t ship an update. Maybe it’s a frozen build you no longer maintain, or it can’t be resubmitted, or there’s simply no v-next on the way. Here’s the freeing part: nothing you do in Keylight can break it, because that old build runs its own licensing and never calls Keylight at all. So you import those customers not to keep the old app alive — it’s already fine on its own — but to make them reachable. Once they’re in Keylight, the customer portal can offer them the move to a new version, and the old build keeps running untouched until each customer upgrades or drifts away on their own schedule.

Your app is shipping a new version. This is the more common case: v-next is going out, and you want existing customers to keep working when they update. You import their keys as they are, and those keys validate in the new build immediately — no re-issuing, no re-delivery. Whether the customer enters that key once or your app reads it for them (the section above) is your call; either way the key they’ve always had is the one that works.

Both paths share the same backbone — import as-is, invalidate nothing — they just differ in whether the old binary is part of the picture at all. If you’re unsure which is yours, the migration overview walks the decision, including the messier cases (missing key strings, very large bases) where emailing us first is the right call.

Shipping a major version (v1 → v15)

A version number does a lot of psychological work here. “I’m going from v1 to v15” sounds like the kind of leap that breaks things. It doesn’t, and seeing why makes the whole migration feel less fragile.

Say you’ve sold v1 through v14 over the years and v15 is the build that adopts Keylight. The sequence:

1. Import the old keys. Upload your customer list as a CSV; every imported license is tagged Migrated so you can see your backlog at a glance. The keys are live immediately.
2. Offer the upgrade. Attach an upgrade to your v15 key type. An upgrade swaps the key type in place and keeps the same key string — a customer’s v1 key simply becomes a v15 key, with v15’s entitlements and limits. They are not handed a brand-new key to install.
3. Let the old versions fade. They keep running on their own; customers come over on their own schedule, and you’re not chasing anyone.

The gap between “1” and “15” never matters, because at no point is a key replaced or revoked out from under a customer. The number is just a label on the product; the key is the thing that has to keep working, and it does.

”Migrated” is provenance, not a downgrade

One last thing worth defusing, because it trips people up: the Migrated label is not a penalty box.

It’s tempting to read it as a second-class status — a license that’s “only sort of” active, or one the customer has to do something to fully claim. It isn’t either. Migrated records where a license came from, full stop. It’s a neutral gray pill in your dashboard so you can tell your imported backlog apart from licenses sold natively through Keylight. It imposes no restriction on the customer, expires nothing, and changes no entitlement. A migrated license and a native one are the same kind of object; one just carries a note about its origin.

That’s deliberate. We don’t auto-remint imported customers or force any change on them, precisely because the whole promise of this migration is “your customers keep what they have.” A flag that quietly downgraded them would break that promise. It doesn’t.

Where to go next

If this is the reassurance you were after and you’re ready to actually do it, the mechanics — CSV columns, the preview-and-confirm flow, when keys are preserved — are in How to Import an Existing Customer Base into Keylight and the migration hub. For the deciding-to-switch view, including the tax-versus-fees tradeoff if you’re leaving a merchant of record, see Migrating Your App’s Licensing to Keylight.

Still not sure your situation is safe? Tell us what you’re migrating from and we’ll talk it through — send us your feedback and we read everything. Keylight starts at $19/month with a free tier, so you can import your base and keep your current setup running alongside it. Full details on Pricing.