Migrate from KeyAuth

GeckoGuard can import KeyAuth applications, licenses, users, expiry dates, safe metadata, bans, subscriptions, and existing HWID bindings. The importer is preview-first: existing records are skipped by default. Enable Reconcile previously imported records for a later snapshot to update matching imported licenses and users.

Use the KeyAuth Seller API from a trusted local script to request type=fetchalllicenses and type=fetchallusers for each application. Store the returned records in one JSON file:

{
  "applications": [
    {
      "id": "legacy-app-id",
      "name": "Desktop Pro",
      "licenses": [],
      "users": []
    }
  ]
}

Do not put a KeyAuth seller key, application secret, password, session ID, or token in this file. Never paste those credentials into GeckoGuard. The importer deliberately strips credential-shaped fields from preserved metadata.

Flat exports are also accepted. Use applicationId on each record when the file contains more than one application:

{
  "applications": [{ "id": "app-1", "name": "Desktop Pro" }],
  "licenses": [{ "applicationId": "app-1", "key": "AAAA-BBBB", "expiry": 1893456000, "hwid": "existing-device" }],
  "users": [{ "applicationId": "app-1", "username": "customer", "email": "customer@example.com", "license": "AAAA-BBBB" }]
}

Expiry values may be ISO dates, Unix seconds, or Unix milliseconds. A missing or zero expiry is treated as no expiry.

2. Preview, correct, then import

Open Dashboard → Migrate, upload or paste the JSON, and select Preview import. Preview performs no writes. Correct every error before importing; warnings explain records that need an operational follow-up.

The importer preserves license keys so installed clients can move without issuing replacement keys. It also preserves active, expired, revoked, and banned states. Imported passwords cannot be reused because KeyAuth does not expose plaintext passwords. Imported users receive an unusable password and must set a GeckoGuard password before using GeckoGuard's end-user login.

Choose Download migration report after preview or import to retain the full JSON report. The page displays the first 100 issues/errors; the download includes all of them. A partial import shows each failed record's identifier and error so it can be corrected and retried. Keep reports private because diagnostics may contain customer identifiers; the original export is not included.

Reconciliation treats the supplied records as authoritative for license status, expiry and HWID, user profile and ban state, and imported metadata. Existing GeckoGuard password hashes and unrelated metadata stay unchanged; KeyAuth passwords are never imported. Matching requires the destination scope and the import identity saved by the importer; use stable application IDs and user IDs across exports. Older imports without that identity need manual reconciliation and are not silently overwritten. Review the updated, skipped, and failed counts after every run.

An omitted record is not a deletion. Export revoked/banned records explicitly, and reconcile removed user-license links manually. Product names and mappings must still resolve to the original destination. Do not use an old export after GeckoGuard becomes your system of record: it could restore superseded state.

3. Use a bounded compatibility window

Do not send KeyAuth seller credentials to GeckoGuard or ship them in a client. During the transition, keep the existing KeyAuth authorization call behind your own server and put this small adapter in front of the two providers. Download the tested adapter, or copy its core below:

export async function authorizeDuringMigration({
  licenseKey,
  authorizeWithGecko,
  authorizeWithKeyAuth,
  fallbackUntil,
  onLegacyFallback = () => {},
}) {
  try {
    return await authorizeWithGecko(licenseKey);
  } catch (error) {
    const stillMigrating = Date.now() < new Date(fallbackUntil).getTime();
    const notImported = error?.errorCode === 'LICENSE_NOT_FOUND';
    if (!stillMigrating || !notImported) throw error;

    const legacy = await authorizeWithKeyAuth(licenseKey);
    if (!legacy?.authorized) throw error;
    await onLegacyFallback({ licenseKey });
    return { ...legacy, provider: 'keyauth-migration-fallback' };
  }
}

Fallback only when GeckoGuard says the key does not exist. Never override an expired, revoked, banned, HWID, signature, or transport failure. Set a fixed fallbackUntil date so legacy authorization cannot remain enabled accidentally, and record every fallback for the final delta import.

4. Cut over without downtime

Prepare the bounded adapter behind a configuration switch, but keep customer authorization on KeyAuth during preparation.
Import the first snapshot. Test GeckoGuard separately and verify counts, expiry, status, user links, and HWID enforcement before routing customers to it.
Freeze KeyAuth administrative writes and automated fulfillment, while leaving authorization available. Export the final snapshot and import it with Reconcile previously imported records enabled.
Resolve every import error and verify the final state, especially revocations, bans, expiry changes, and HWID changes. A successful preview alone does not prove those updates were applied.
Switch customers to GeckoGuard-first authorization with the bounded missing-key fallback. Resume administrative writes and fulfillment only in GeckoGuard. Keep KeyAuth writes disabled and observe authorization events and fallback logs through a normal customer cycle.
Confirm the fallback log remains empty, disable fallback before its deadline, then revoke the KeyAuth seller key and remove KeyAuth secrets from servers and CI.

This preserves authorization availability while requiring a short administrative write freeze. If verification fails before the switch, keep customer traffic on KeyAuth and correct the import. After GeckoGuard accepts new writes, a rollback needs reverse reconciliation; switching blindly to the old KeyAuth snapshot could restore revoked access or lose new licenses.

What to verify

A valid imported key authorizes and appears in the GeckoGuard event stream.
Expired, revoked, and banned records remain denied.
Existing HWID-bound licenses accept only their current device.
A newly created GeckoGuard license never falls back to KeyAuth.
Users who need the customer portal complete a GeckoGuard password setup.
The final fallback count reaches zero before KeyAuth credentials are retired.

Migrate from KeyAuth

1. Export without sharing your seller key

2. Preview, correct, then import

3. Use a bounded compatibility window

4. Cut over without downtime

What to verify