Enrollment and device credentials

Per-device credentials, not shared keys

Scout v0.3.0 introduced secure enrollment: instead of every agent in the fleet sharing one org-wide ingest key, each device exchanges a limited-use enrollment token for its own revocable per-device credential. A lost laptop no longer means rotating a key that hundreds of other machines depend on — you revoke that one device.

As of Scout v0.6.0 this is the only way a Scout authenticates. The org-wide ingest api_key and the username / password login have been removed from the agent — there is no code path left that can send either, and a scout.toml that still names one refuses to start. Read Upgrading from a legacy configuration below before you upgrade.

How enrollment works

1. Mint a token under Inventory → Agents → "Deploy Scout". Tokens look like sce_…, can carry a use limit and an expiry, and can pre-assign a Group. The preconfigured Windows setup wizard embeds one automatically.
2. The agent enrolls on first start: it calls POST /api/v1.0/inventory/enroll with the token and its identity (hostname, OS, machine ID, serial number) and receives a private device key (scd_…) — returned exactly once and stored hashed on the server.
3. The device key is persisted in the agent's state file, and every subsequent report and config poll authenticates with it (X-Device-Key). The enrollment token is no longer needed and can expire harmlessly.

Platform	State file (device credential)
Windows	C:\ProgramData\VerOps\Scout\scout-state.toml
Linux	/etc/verops/scout-state.toml (mode 600)

The location can be overridden with state_path in scout.toml (or SCOUT_STATE_PATH). Deleting the state file makes the agent re-enroll — which only succeeds if its enrollment token is still valid.

The only two credentials

From v0.6.0 a Scout has exactly two credentials, and one of them exists only long enough to obtain the other:

Credential	Header / flow	Lifetime	Scope
Enrollment token sce_… (in scout.toml)	Exchanged once at POST /api/v1.0/inventory/enroll	Limited-use and expiring — it may be spent and gone before the laptop is even handed over	Mints device keys; carries no ability to read or report anything itself
Device key scd_… (in the state file)	X-Device-Key on every report and config poll	Long-lived until you revoke it	This device only — revocable individually, with no effect on any other machine

That is the whole security argument for the change. The thing you distribute — the token — is nearly worthless once used and cannot be used to impersonate a fleet; the thing that is powerful — the device key — is never distributed, never appears in a config file you copy between machines, and revoking it takes exactly one machine offline.

Every Scout request also carries an X-Agent-Kind: scout header, so the platform knows which product is calling. Inventory ingest refuses an org-wide API key from a Scout on that basis, regardless of whether the key itself is valid.

Upgrading from a legacy configuration

Scout v0.5.0 and earlier also accepted an org-wide ingest api_key (ta_live_…) or a platform user's username / password. Both are gone from v0.6.0, and this is a breaking change for any machine still configured that way:

• A Scout v0.6.0+ that finds api_key, username or password in its config will not start. It exits with a configuration error (EX_CONFIG, exit code 78) and writes a message naming the config file, each offending key, any SCOUT_* environment variable that supplied one, and how to fix it. The failure is deliberately loud: systemctl status verops-scout or the Windows Service Control Manager shows you the reason rather than a machine that silently went quiet.
• Presence is what counts, not the value. api_key = "" still names a removed credential and is still refused.
• Scout v0.5.0 and earlier keep working against the platform unchanged. Nothing breaks on the server side, so you can pace the migration — but every machine must be migrated before its agent is upgraded, not after.

Two ways to migrate a machine:

1. Re-deploy it (recommended). Build a fresh package from Inventory → Agents → "Deploy Scout" and run it on the machine. The package carries a valid enrollment token and no legacy keys, and the installer restarts the service so the new configuration takes effect immediately. A machine that has already run Scout notices the token changed and re-enrolls — it keeps its identity, its history and its place in the estate.
2. Hand-edit the config. Delete the api_key / username / password lines from scout.toml, add an enrollment_token minted under Deploy Scout, and restart the service. Clear the matching SCOUT_API_KEY / SCOUT_USERNAME / SCOUT_PASSWORD environment variables too if your deployment sets them.

An unconfigured agent is a deliberate exception: a Scout with no credentials at all is not refused. It logs an error and idles, because the generic installer starts the service before anyone has filled the file in.

The Machine Agent is not affected. The VerOps Machine Agent (v0.5.0) still supports an ingest api_key for its inventory module, and its own machine connection key is untouched. Do not strip api_key out of a machine-agent config — the two agents deliberately differ, and the platform tells them apart by the X-Agent-Kind header each one sends.

Revocation and re-enrollment

• Revoke a device from Inventory → Agents (row menu → revoke credential). The agent's next request is rejected; it stops reporting until re-enrolled. Do this when a machine is retired, lost, or compromised.
• Revoke a token from the Deploy Scout token list — it can no longer mint device keys; already-enrolled devices are unaffected.
• If a device key is rejected, the agent automatically attempts one re-enrollment with its configured enrollment token (if still valid), then retries with throttled warnings. It never deletes its state file on its own.
• Re-deploying re-enrolls. From v0.6.0 the agent remembers which enrollment token it used (as a hash — the token itself is never stored). Running a fresh Deploy Scout package on a machine that already runs Scout writes a new token, and the agent notices and enrolls again, keeping its identity and history. Re-running a package with the same token changes nothing, so re-deploying is safe to repeat.

Stable machine identity

Enrollment also ties the device to a stable machine identity: the OS machine ID (MachineGuid on Windows, /etc/machine-id on Linux) plus the DMI serial number. A renamed host stays the same asset in the estate — history, tags, and usage follow the machine, not the hostname.

Note: The same enrollment flow is available to the Machine Agent's inventory module on servers (agentKind=server) and is the recommended setup there too — see the Machine Agent inventory module. The machine connection key is a different credential again and cannot authenticate inventory endpoints.