Connecting many sites at once

When you’re moving a lot of sites, pasting a key into each one takes too long. An enrollment key lets you install the WP Foreman plugin on all of them at once (from ManageWP, MainWP or WP-CLI) and approve them as they arrive. This page explains how it works and why a leaked key can’t hurt your sites.

The short version

• An enrollment key only lets a site ask to join your account. It can’t read, change or control any site, new or old.
• Every site still connects with its own keys, exactly like a site you add by hand (see How WP Foreman connects to your site). The enrollment key isn’t used after the site has asked.
• Nothing joins until you approve it, and only after WP Foreman has checked the site really is at the address it gave.
• Keys expire (after 7 days unless you choose otherwise), can be limited to a number of sites, and can be revoked with one click. WP Foreman keeps only a fingerprint of each key, never the key itself.

How to connect many sites

1. Go to Sites › Connect many sites and click Make a key. Give it a name, choose when it expires and, if you like, how many sites it’s for and which client the new sites go under.
2. Pick how to install the plugin:
   • ManageWP or MainWP: click Download plugin with key and bulk-install that zip from your old tool, with activate ticked.
   • WP-CLI: copy the command and run it in each site’s WordPress folder. It installs the plugin and runs wp wpforeman enroll with your key.
   • One site by hand: the usual way, with a one-site connection key. Nothing changes there.
3. Each site appears under Waiting for approval within a minute or so. Tick the ones you expect and click Approve (or Approve all confirmed). Each one connects within a few minutes.
4. When you’ve moved everything, revoke the key.

You can see the key, copy the command and download the zip for two hours, and only in the browser where you made the key. After that WP Foreman only knows its last four characters. Need it again? Make a new key.

What an enrollment key can and can’t do

With an enrollment key, a website can put itself on your Waiting for approval list. That’s all.

• It can’t connect a site without your approval (unless you switch on auto-approve for your own domains, below).
• It gives no access to the sites already in your account, their backups, or your settings.
• It can’t be used to sign commands. Commands are signed with WP Foreman’s own key, and each site checks them with its own stored copy, exactly as before.
• The zip you download has the key inside it, so treat the zip like the key. It stops working the moment the key expires or you revoke it.

The address check

A site asking to join tells WP Foreman its address, its name and the public half of the key pair it just made for itself. Before you can approve it, WP Foreman contacts the site at that address and asks it to sign a fresh random challenge with its key. Only the real site, holding the key it asked with, can answer.

So someone with your key can’t pretend to be one of your clients’ websites: they’d have to control that website. Requests that don’t pass show Not confirmed with the reason and can’t be approved. If a firewall or bot check is in the way, allow WP Foreman through (see Allowlisting WP Foreman) and click Check again.

Approving, declining and auto-approve

• Approve adds the site to your account and to your plan’s site count. It connects with its own keys the next time it checks in (within a few minutes).
• Decline tells the site it wasn’t accepted. It can’t ask again with the same key.
• A site that’s already connected in your account can’t be added again through an enrollment key. To move it, use its Site settings › Reconnect.
• Auto-approve (off by default) approves sites whose address matches domains you list, like example.com or *.clientsites.com. They still have to pass the address check. Only the account owner can switch it on.
• Requests nobody decides on drop off the list after 30 days.

If a key leaks

The worst that can happen: someone puts their own website on your waiting list. You’d see a site you don’t recognize, and decline it. They get no access to your sites, your backups or your account.

To shut it down, click Revoke next to the key. WP Foreman offers to decline every site still waiting that used it too. Then make a new key for the sites you’re still moving.

Everything is recorded

Every key made, revoked or downloaded, every request to join, and every approval or decline is recorded with who did it and when. An approved site’s site log shows both steps: when it asked to join (with the key it used and where it came from) and who approved it.

If this sounds familiar

It’s the same idea as Tailscale’s auth keys and the enrollment tokens companies use to sign up laptops to their device management: a short-lived key that lets a device ask to join, with each device then getting its own credentials, and an administrator in charge of who’s let in.

Questions

Do I need the new plugin? Yes: WP Foreman plugin 0.11.0 or later, which is what the zip and the WP-CLI command install. Sites you already connected don’t need to do anything.

The site says “Waiting for approval” but isn’t on my list. Check it’s the right account (if you’re on a team, the account you were in when you made the key), and that the key hadn’t expired. The plugin’s page (Settings › WP Foreman) shows where things stand, with Check now.

A site lives in a subfolder (example.com/blog) or on a special port. Those can’t join with an enrollment key, because the address check works on the whole domain. Connect them with their own connection key from the Sites page. The same goes for subfolder sites in a WordPress multisite network.

What about sites I add after the move? Keep adding them with a one-site key from the Sites page, or make a new enrollment key whenever you have a batch.