The agent Enrolling many machines

Enrolling many machines

An install command enrolls one machine, then it is spent. To enroll a fleet without minting a command for each computer, issue a reusable secret. You bound it with a number of machines and an expiry, and you put it where your MDM tool can hand it to every machine.

Both kinds of credential are shown once. The server keeps only a digest, so it cannot show either again. If you lose one, issue another.

Who can do it

Minting an install command and issuing a secret both need the fleet:manage permission. Without it the console says: You can view this fleet but not manage its enrollment. This needs the fleet:manage grant.

One machine, or many

In Enroll machines, after you choose a profile, the Install step asks How many machines?

	One machine	Many machines (MDM)
Credential	An install command	A secret and an MDM payload
Uses	Exactly one machine, then it is spent	Up to the number you set
Valid for	24 hours after you create it	The time you set: 7, 30 or 90 days
You choose	Nothing	Up to and Expires in
Button	Create install command	Issue secret

Either way, the machines that enroll get exactly the configuration of the profile you chose. A machine cannot supply its own.

Issue a secret

Go to Inventory › Machines and choose Enroll machines.
Choose or create a profile. See Deployment.
On the Install step, choose Many machines (MDM).
Under Up to, enter the most machines it may enroll, as a whole number of at least 1. There is no upper limit.
Under Expires in, choose 7 days, 30 days or 90 days.
Choose Issue secret.

Neither field is preselected, and Issue secret stays disabled until both are set. A reusable credential is only safe with a bound, so you choose it every time.

The console then shows:

a line such as Enrolls up to N machines, valid until the expiry time;
the Secret, shown once, with a copy button;
the MDM payload, with a copy button and Download .json.

Tick I have stored this somewhere safe. Done and Issue another stay disabled until you do, and the dialog will not close another way, because the server cannot show the secret again.

The MDM payload

The payload is a flat JSON object with three keys:

Key	Value
`server_url`	The console's address, which the agent enrolls against
`secret`	The reusable secret
`profile_name`	The name of the profile, so whoever pastes it later knows which one it is

It is not written for any one MDM vendor. Most MDM tools accept an arbitrary set of keys and values, so you can paste it as it is.

A machine presents the secret in the same place as a one-machine token. With the install commands that is -Token on Windows and --token on macOS and Linux, so a script that runs the install command with the secret enrolls the machine. How you deliver that script is up to your MDM tool.

What counts against the limit

Each enrollment with the secret uses one of its Up to machines.
The secret stops working when its count is used up, when it expires, or when its profile is revoked. A machine that tries it then is told: enrollment credential is not recognised, expired, revoked, or already used.
If your plan's Machines limit is already reached, the machine that would pass it is refused, and the secret keeps that use.

To issue a different bound, choose Issue another. Each secret has its own limit and expiry, and issuing a new one does not change an earlier one.

With the API

Both credentials are created by the API as well.

POST /enrollment-profiles/{id}/token mints a one-machine token, valid for 24 hours.
POST /enrollment-profiles/{id}/secret issues a secret. Its body has max_enrolments, a whole number above 0, and expires_at, a future time in RFC 3339 form. The console offers 7, 30 or 90 days. The API accepts any future time.
POST /enrollment-profiles/{id}/revoke revokes a profile and every credential minted from it.

The calls need fleet:manage, and minting a token or issuing a secret is recorded in the audit log (enrollment_profile.token_minted and enrollment_profile.secret_issued). See the API reference.