Install tokens & enrollment

An install token is how a device becomes a CertIntel agent without ever typing a real API key into an installer. It's created once per organization, distributed to whoever runs the installer, and exchanged - automatically, by the agent itself - for a brand-new, device-specific API key.

Why not just use an API key directly?

An install token can do exactly one thing: mint a fresh, write-scoped agent key. It cannot read or write monitoring data itself. That means:

• Rotating or revoking the install token never breaks a device that's already enrolled - each device holds its own independently-issued key.
• The same token can enroll any number of devices; you don't need a new one per machine.
• If the token leaks, the blast radius is bounded to "someone can create new pending device identities in this organization" - not "someone can read your certificate inventory."

Create or rotate a token on the Install Tokens page. Reveal shows the same secret again (it's recoverable, unlike a regular API key's secret) so you don't have to rotate just to see it a second time.

Enrollment: pending by default

When an agent exchanges an install token, the new key is created in a pending state - it exists, but every request it makes is refused until an administrator approves it. This closes a real gap: without it, a leaked or guessed install token could quietly self-enroll a working credential that nobody would notice until they happened to check.

A pending agent's requests get 428 Precondition Required (not a generic 401). The Windows Agent may still show that a local credential is present because the install-token exchange succeeded; that state does not mean the platform has approved the credential. Use Test connection and Activity to see the pending-approval response.

On the Agents page, a pending device shows a Pending approval badge and an Approve button. Before approving, check that the device name and organization look right - this is the point where you decide whether a newly-appeared device identity is one you actually expect.

Once approved, the device reports normally. Rotating or revoking the install token afterward has no effect on it.

Unregistering a device

When someone runs the agent's local unregister command - taking a device out of service, or removing a saved API key on the agent's own machine - the agent calls CertIntel once, right before it discards its local copy of the key, to say "I'm done with this credential."

That call does not revoke the key. It sets a separate, purely informational flag: Unregistered locally at <time>, shown on the Agents page instead of a misleadingly-fresh "last seen" timestamp. The key still works if it's ever presented again (say, the same secret gets restored from a backup) - CertIntel is just telling you the device said it was leaving, not making that decision for you. It's a deliberate two-step: the device reports "I'm gone," an administrator decides whether that also means "revoke this."

This call works the same whether the device enrolled via install-token exchange or was set up by pasting an existing integration key into the agent directly (its "connect using an API key" path) - either way, the key can only ever flag itself, so there's nothing extra to authorize.

What to do with a flagged device

The Agents page's Unregistered locally state is informational, not a verdict. From there:

• Revoke it if the device is genuinely retired and you don't expect it back.
• Rotate it if you expect a reinstall to reuse the same identity soon.
• Leave it if you're not sure yet - it costs nothing to wait, and the badge keeps it visible until you decide.

Agent states at a glance

State	Meaning
Pending approval	Freshly enrolled; every request is refused until you approve it.
Active	Approved, not revoked, reporting normally.
Unregistered locally	The device itself said it's disconnecting. Still a live, usable credential until you act on it.
Disabled (revoked)	An administrator turned it off. Reactivate to bring it back.