Skip to Main
View .mdAsk ClaudeAsk ChatGPT

Migrating a HuxxConnect site to a new server, host, or clone triggers the Environment Lock: the destination shows “Environment mismatch — credentials are locked.” and stops decrypting credentials until you prove the move was intentional. This page is the playbook for a planned move on the Standard encryption tier, plus every recovery path when the plan slipped.

Quick version:

  1. Before migrating, on the source site: HuxxConnect → Settings → Security → Migration & Portability → Passphrase tile → Generate Migration Passphrase. Copy it — it is shown once and valid for 72 hours.
  2. Migrate the site normally (files + database).
  3. On the destination: HuxxConnect → Settings → Security → Unlock Credentials → Passphrase tile → paste the passphrase → Unlock.
  4. Done — credentials decrypt again, and the lock re-seals against the new server.
New to APIs? Read this first

Your API configurations, endpoints, and pages all migrate normally either way. The lock only pauses access to the stored secret values (tokens, keys, passwords) until the new server is confirmed. See Environment Lock Explained.

Step 1 — Generate the passphrase on the source site

Do this before you take the migration snapshot, while the source site is unlocked.

  1. Go to HuxxConnect → Settings. In the Security card, under Migration & Portability, click the Passphrase tile.
  2. Click Generate Migration Passphrase.
  3. The passphrase appears once, in the format XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX, below the warning “Save this passphrase — it will not be shown again!” — that warning is literal. Only a hash of the passphrase is stored, so nothing can re-display it. Click Copy to Clipboard and save it in a password manager.

Three properties to plan around:

  • 72-hour validity, counted from generation. While the passphrase is still valid, returning to the panel shows the status line “Active passphrase — expires in …” with the remaining time; once the 72 hours pass, the status line disappears and the Generate Migration Passphrase button returns — regenerate.
  • One active passphrase at a time. Generating a new one invalidates the previous one.
  • It must be generated before the database snapshot you migrate — the hash has to be inside the database that arrives at the destination.

If the same migration happens repeatedly (production ↔ staging), pre-authorize the domains instead and skip the passphrase entirely — see Configure Environment Lock.

Step 2 — Migrate

Use your normal migration tooling — files and database. Nothing HuxxConnect-specific is required in this step.

Step 3 — Unlock on the destination

  1. On the destination site, go to HuxxConnect → Settings. The Security card shows the lock banner and an Unlock Credentials section with method tiles.
  2. Click the Passphrase tile (“Enter the migration passphrase from the source server.”).
  3. Paste the passphrase and click Unlock.

On success you get an “Environment unlocked!” confirmation, the used passphrase is cleared, and the lock is re-established against the new server — including auto-authorizing the destination domain for future round trips.

Recovery paths — no passphrase, or it went wrong

No passphrase was generated (or it expired) — use the wp-config challenge. In Unlock Credentials, click the wp-config Challenge tile, then Generate Challenge. Add the displayed line to the destination’s wp-config.php:

define( 'HUXX_CONNECT_AUTHORIZE', 'the-generated-challenge-code' );

Click Verify. Editing wp-config.php proves server control, which is what the lock needs. Remove the constant afterward. Caveat: if the encryption key itself didn’t survive the move, the challenge dismisses the lock but credentials still need re-entry — the notice will say so.

Advanced tier — copy the constants instead. If the site uses the Advanced tier, there is no passphrase step at all: copy HUXX_CONNECT_ENCRYPTION_KEY and HUXX_CONNECT_ENCRYPTION_SALT from the source server’s wp-config.php into the destination’s, and the plugin unlocks automatically. If you migrated without them, the Settings page shows an “Encryption key not found” notice with a Restore Credentials snippet to paste them into.

Locked tier — re-enter credentials. On the Locked tier the encryption key is derived from the source server’s WordPress salts and does not exist on the destination. There is nothing to unlock; the plugin clears the lock itself, so the Settings page shows the normal unlocked view. Instead, HuxxConnect screens show an admin notice titled “HuxxConnect: Environment Changed” (“This site uses server-locked encryption. API credentials from the previous server cannot be decrypted and must be re-entered…”), and the Security card’s Credential Health table lists every API whose credentials can no longer be decrypted. Re-enter each affected API’s credentials on its configuration page. See Encryption Tiers Explained.

Remote Unlock (Pro) — if the source site is still online, the destination can verify itself against it directly, with no passphrase and no wp-config.php edit. See Unlock credentials remotely.

If it didn’t work

“Invalid passphrase.” — Almost always a transcription problem: paste the full 39-character value including the dashes, with no leading or trailing whitespace. Also confirm no one generated a newer passphrase before the migration snapshot was taken — generating a new one overwrites the stored hash that travels in the database. After 5 failed attempts within 15 minutes you’ll see “Too many attempts. Please wait 15 minutes before trying again.” — wait out the window before retrying.

“Migration passphrase has expired. Generate a new one from the original site.” — More than 72 hours have passed since generation. If the source site still exists, generate a fresh passphrase there — but note the destination’s database won’t contain its hash, so for an already-migrated snapshot use the wp-config challenge instead.

“Passphrase unlock requires the original encryption key. Copy it from the source server or use the wp-config.php challenge instead.” — The destination is on the Advanced tier but the key constant is missing, so the passphrase hash can’t be verified. Copy the two encryption constants from the source wp-config.php (see the Advanced-tier recovery path above), reload, and unlock again — or fall back to the wp-config challenge and re-enter credentials.