---
title: "Configure Environment Lock"
slug: configure-environment-lock
type: how-to
plugin: huxx-connect
summary: Pre-authorize the domains your site migrates between so credentials unlock automatically, and know exactly which changes trigger a lock.
keywords: [environment lock, authorized domains, migration, security, staging]
version_added: 1.2.5
version_updated: 1.2.5
level: intermediate
related: [environment-lock, move-a-locked-site, encryption-tiers, unlock-credentials-remotely]
---

Environment Lock pauses credential decryption when your site lands on an unfamiliar server. The main thing to configure is the **authorized domain** list: domains you trust in advance, so that a migration to one of them unlocks automatically with no passphrase ceremony. Background: [Environment Lock Explained](/docs/connect/explanation/environment-lock/).

> **Quick version:**
> 1. **HuxxConnect → Settings** → **Security** card → **Migration & Portability** → click the **Authorized Domains** tile. (Shown on the Standard encryption tier only.)
> 2. Enter each domain the site may run on (e.g. `staging.example.com`), click **Add Domain**.
> 3. Do this **before** migrating, while the site is unlocked. After migration to an authorized domain, credentials unlock automatically.

## What triggers a lock (and what doesn't)

The lock fires when the environment fingerprint — an HMAC of this install's WordPress salts, keyed by the encryption key — no longer matches. In practice:

| Change | Locks? |
|---|---|
| Migrating/cloning the site to another server or host | Yes |
| Restoring the database onto a fresh WordPress install | Yes |
| Rotating the WordPress salts in `wp-config.php` | Yes |
| Changing the site's domain only (same install, same salts) | No |
| Plugin updates, editing APIs, changing settings | No |

Tier behavior differs on a mismatch: **Advanced** unlocks automatically when its `HUXX_CONNECT_ENCRYPTION_KEY` constant is present on the new server, and **Locked** skips the lock entirely because its credentials are already unrecoverable after a move. The authorized-domain machinery is therefore a **Standard-tier** tool, and the Settings UI only shows the migration tiles on Standard. See [Encryption Tiers Explained](/docs/connect/explanation/encryption-tiers/).

## Add authorized domains

1. Go to **HuxxConnect → Settings**. In the **Security** card, find **Migration & Portability**.
2. Click the **Authorized Domains** tile to expand its panel.
3. Type the domain — hostname only, e.g. `staging.example.com` — and click **Add Domain**. Full URLs are accepted and reduced to their hostname; ports and paths are stripped.
4. Repeat for every domain the site legitimately runs on: staging, production, a dev copy.

<!-- screenshot-todo: settings--security--authorized-domains | alt: Authorized Domains panel with the domain input, Add Domain button, and existing domain tags -->

Each added domain appears as a tag. Your current domain is listed automatically with a **(current)** marker — HuxxConnect self-authorizes it whenever the lock is established, so a round trip (production → staging → production) unlocks at both ends.

:::novice
Nothing here changes how requests are made. This list only tells HuxxConnect which of *your own* domains it should trust after a site move. See the [glossary](/docs/connect/explanation/glossary/#credentials) for what credentials are.
:::

Two constraints to know:

- **Domains can only be added while the site is unlocked.** Authorization tokens are computed with the encryption key, and handing out authorizations from a locked (untrusted) state would defeat the mechanism. Plan ahead: add the destination domain before you migrate.
- **You can't remove the current domain** — that would be self-lockout on the next check. Any other domain's tag has a remove button.

## How the auto-unlock plays out

After you migrate to `staging.example.com` (already authorized), the first admin page load detects the fingerprint mismatch, finds a valid token for the requesting domain, unlocks, and re-seals the lock against the new server — including re-authorizing the new current domain. You see no lock screen at all. If the domain is *not* on the list, you land in the locked state and need the [migration playbook](/docs/connect/how-to/move-a-locked-site/).

## If it didn't work

**The Authorized Domains tile isn't visible.** — Either the site is not on the Standard tier (Advanced shows a copy-the-constants notice instead; Locked shows no migration tools because its credentials can't migrate), or the site is currently locked — the Security card is showing **Unlock Credentials** instead. Unlock first, or check the **Active** tier tile under **Encryption Key Source**.

**Migrated to an authorized domain but still locked.** — Most often the domain was added *after* the database snapshot used for the migration, so the destination's database has no token for it. Unlock with the migration passphrase or the wp-config challenge (see [Move a Site with Locked Credentials](/docs/connect/how-to/move-a-locked-site/)), then re-add the domain. This also happens when the entry doesn't match the exact hostname being requested — `www.example.com` and `example.com` are different domains; authorize both if you use both.

**"Invalid domain or domain not found."** — The value reduced to nothing valid after sanitization (a bare word with no dot, for instance — `staging` instead of `staging.example.com`). Enter a fully qualified hostname. If the site became locked in the meantime you'll see **"Cannot modify authorized domains while environment is locked."** instead — unlock first. (A generic "Failed to add domain." appears only when the request itself failed at the network level.)