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 is handed to whoever runs the installer and exchanged - automatically, by the agent itself - for a brand-new, device-specific API key. There are two kinds:

Both kinds produce the same pending agent credential and the same install commands; only the token's lifetime differs.

Quick install¶

1. Open Install Tokens. Every organization already has a token; its row shows only the token's prefix (cit_xxxx…) with Show, Install on Windows, Install on Linux, Rotate and Revoke buttons. The list itself has no install command. Click Install on Windows or Install on Linux (or Show, or the row) to open the token's own page at that operating system's section; it shows the full token, its Child organization, a Copy token button, a jump bar for the OS sections, the Installation options and the generated commands. Every view of that page is recorded in the activity log as install_token.reveal. Rotate lands on the same layout (Install token ready) with the new value. (Platform builds up to 2026.10.28 showed the full value in the list and had only Show.)
2. On the token page, choose your Installation options:
   • Mode: Interactive (the installer shows its wizard and prompts when needed) or Silent (never prompts; for deployment tools).
   • API base: leave https://api.certin.tel unless you run a private CertIntel; enter the HTTPS origin only, with no path or trailing slash.
   • Reset existing data: remove an existing agent's connection and local data before reinstalling. On Linux this also removes the service, package, binary, state directory and service user.
   • Trust the CertIntel code-signing certificate (Windows only): add the installer's signing certificate to the machine's Trusted Root and Trusted Publishers stores so Windows shows CertIntel as a verified publisher. Linux releases are verified by SHA-256, not a code signature.
3. Still on the token page, click Copy commands under PowerShell (elevated), cmd.exe / RMM one-liner or Bash, and run it on the device.

The generated commands download a small bootstrap from https://certin.tel that resolves the current release, cross-checks two independent signed release records, verifies the versioned installer (SHA-256, plus the pinned Authenticode signature on Windows) and then runs it. The token stays in an environment variable rather than on the command line.

$env:CI_INSTALL_TOKEN = "cit_..."
& ([scriptblock]::Create((irm https://certin.tel/install.ps1))) -NonInteractive

curl -fsSL https://certin.tel/install.sh | sudo env CI_INSTALL_TOKEN="cit_..." bash -s -- --non-interactive

Enter the token exactly as supplied, without adding a label, whitespace or newline to the value. The installer passes credentials exactly rather than trimming or repairing them. Show opens an existing install token again; its response is not cacheable. Avoid saving populated commands in tickets, deployment logs, or source control, and clear the parent shell's token environment variable after installation.

For the full installer behaviour, the MSI, and step-by-step verification, see Windows Agent and Linux Agent. A native Agent's API-key connection path is for an existing agent credential; use an install token to create a new device identity.

Minting a one-time token for a hands-on install¶

On platform builds after 2026.10.28, anyone who may Show an install token (permission install_tokens.reveal) can mint a one-time install token instead of handing out the organization token: it is shown once, enrolls exactly one agent and then stops working, so there is nothing to rotate or clean up after a one-off install.

1. Open Install Tokens and find the card Mint a one-time install token (the same form sits in the Agents page's empty state, under Installing by hand? Mint a one-time install token: shown once with the install commands, good for a single enrollment, and it expires on its own.). Choose the Organization (shown only when you have more than one) and Expires after: 15 minutes, 1 hour (default), 4 hours or 24 hours, then click Mint one-time token.
2. The page One-time install token ready is the only place the token is ever shown. It says so: This token is shown only now. It enrolls exactly one agent and stops working after that install or at <expiry>, whichever comes first. It is not stored, so if you leave this page without copying the command, mint a new one. Below the notice are the same Installation options and ready-to-copy Windows and Linux commands as on the organization token's page (irm https://certin.tel/install.ps1 | iex and curl -fsSL https://certin.tel/install.sh | sudo bash, unchanged).
3. Copy the command, run it on the device, and approve the new agent on the Agents page exactly as with the organization token (see Enrollment: pending by default).

The first successful exchange consumes the token. A second attempt is refused with This one-time install token has already been used. Mint a new one from the Install Tokens page., and an attempt after the expiry with This one-time install token has expired. Mint a new one from the Install Tokens page. (both 401). A wrong secret, a revoked token or a failure of the organization token still gets the generic Invalid install token.; the two specific messages appear only when the secret itself matched. See troubleshooting.

Because the token is never stored, the list cannot bring it back: Show bounces to the list with A one-time install token is shown only when it is created and is never stored. Mint a new one if it was lost., Rotate answers A one-time install token cannot be rotated. Mint a new one instead. and Reactivate A one-time install token cannot be reactivated. Mint a new one instead. The only action a live, unused one-time token offers is Revoke.

The Install Tokens list¶

On platform builds after 2026.10.28 the list shows every token of both kinds with the columns Organization, Token (prefix only), Kind (a pill reading organization or one-time), Status (active for an organization token; unused, used, expired or revoked for a one-time token), Expires, Last used and Actions. Organization rows keep their row link and the Show, Install on Windows, Install on Linux, Rotate, Revoke and Reactivate buttons; one-time rows have no row link and only Revoke while they are unused and live.

Used, expired and revoked one-time tokens stay in the list with their state for seven days after the earliest of those moments, then the platform's daily retention task deletes them (deployment setting CERTINTEL_RETENTION_ONE_TIME_INSTALL_TOKENS_DAYS, default 7). Organization tokens are never purged, and an agent enrolled through a token that has since been purged keeps working: its credential is its own.

Activity log¶

Minting writes install_token.create_one_time (User X created the one-time install token cit_…, valid for 60 minutes.); an enrollment through one is an install_token.exchange event ending in using a one-time install token.; and every install_token.* event records the token's kind. Viewing an organization token is still install_token.reveal.

API¶

POST /api/v1/install-tokens/one-time (permission install_tokens.reveal) mints a token. The body takes an optional organization (id or slug; required only when the caller can act in several) and expires_in_minutes as 15, 60 (default), 240 or 1440; any other value is a 422. The 201 response is sent with Cache-Control: no-store and is the only time the secret appears:

{
  "id": "…",
  "organization_id": "…",
  "kind": "one_time",
  "prefix": "cit_xxxx",
  "created_at": "…",
  "expires_at": "…",
  "last_used_at": null,
  "revoked_at": null,
  "used_at": null,
  "secret": "cit_…"
}

GET /api/v1/install-tokens and every token response now include kind (organization or one_time) and used_at. The reveal, rotate and reactivate routes answer 409 for a one-time token (and reactivate answers 409 This install token is not revoked. for a live organization token); revoke works for both kinds. The agent-side exchange route is unchanged.

Why not just use an API key directly?¶

Short answer: an install token can't do anything but mint a new agent key, so handing it to an installer is much lower-stakes than handing out a real API key.

Long answer: 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 organization token can enroll any number of devices; you don't need a new one per machine. When you would rather not hand the long-lived token to someone installing by hand, mint a one-time token instead.
• 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."

Rotate the organization token on the Install Tokens page (one is issued per organization automatically) when it may have leaked: rotation keeps the prefix and replaces the secret in place, the old secret stops working at once and no copy of it is kept, so a revoked token can be reactivated only as it is, never to an old secret. Rotating never affects one-time tokens. Show (and the Install on … buttons) display 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, and each view is written to the activity log as install_token.reveal; a token created before secrets were stored cannot be shown and must be rotated.

Enrollment: pending by default¶

When an agent exchanges an install token (of either kind), 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 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 (Windows) or certintel diagnostics and Activity to see the pending-approval response. The Windows app reports Approval required: Approve this agent in the CertIntel dashboard, then test the connection again.; the command line returns code approval-required with this agent is waiting for approval; approve it in the CertIntel dashboard, then test the connection again. Agent 1.3.93 and later also record one approval-pending event in Activity, report approval_pending: true in certintel status --json and log approval-granted once they notice the approval.

On the Agents page, a pending device shows a pending approval badge and an Approve button. Before approving, check that the device name, OS 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. Until its first heartbeat or report arrives, the row reads Approved – waiting for first heartbeat. The agent checks for approval about every 15 minutes and reports as soon as it is approved; restart the CertIntel Agent service to send it now. (platform builds after 2026.10.28); an unapproved key keeps Awaiting first report with the pending approval pill. When no agent is enrolled at all, the page offers Install on Windows / Install on Linux per organization, which open the organization token's page at the matching section, and the one-time token form under Installing by hand? Mint a one-time install token … (see Minting a one-time token).

The Agents page¶

Each row shows the device, its OS (Windows, Linux or macOS, reported by agents 1.3.56 and later; older agents show a dash), the agent version, the API key prefix, organization, roles, last-seen time and state. Details opens the device's reporting history. Agents 1.3.62 and later also send an hourly heartbeat (Agent 1.3.93 and later: about every minute for the first 15 minutes after approval, then hourly), so a device that is running but has nothing to report (no monitors, no assigned checks, no certificate work) still shows a fresh last-seen time and its current version; the heartbeat is not a check-in and never restores a disabled or unregistered device. Available actions:

Credential approval does not mean an agent is reporting; freshness is shown separately and only counts approved, unexpired, enabled agent credentials.

A Locked pill on the row (Agent 1.4.0 and later) means a local administrator turned on the device's configuration lock: the Agent applies no dashboard-assigned workflows until it is removed on the device, while renewals and deployments continue. The device's detail shows a Configuration lock row with the time it was turned on, and a Deferred deployments table lists renewed certificates waiting for a deployment window. See configuration lock.

On a platform build that offers them, the device's detail also has these sections:

• Agent update - the update request below.
• Platform credentials - whether the Agent accepts platform credentials for appliance deployments, its pinned sealing key, and Approve new key when it reports a new one.
• Private CA roots - whether the machine trusts each Private CA root, per trust store (Agent 1.5.0 and later).

Agent updates from the dashboard¶

On a platform build that offers the feature, an Update available pill on the Agents list and the host detail page marks an Agent older than the latest signed release the platform holds. The Updates filter (Any or Update available ()) lists only those Agents.

Update now (on the host detail page's Agent update section, and on each row) and Update all outdated () (above the list) ask Agents to update to that version. The confirmation names the count and the version, and the skipped Agents. The rule is The platform requests; each device decides.:

• The Agent picks the request up with its next heartbeat, within about an hour.
• It installs only the version in the signed release manifest it verifies itself (the requested version or a later one), never a download address from the dashboard, and never a downgrade.
• It installs only when a local administrator turned automatic installation on (see Windows updates and Linux updates); otherwise it refuses with automatic installation is off on the device. The configuration lock does not block signed updates.
• Linux Agents refuse in this release (automatic installation is not available in this release); update them on the device with sudo certintel update install, or with apt or dnf for package installs.
• Agents before 1.5.0 show Requires Agent 1.5.0 instead of the button and are skipped by Update all outdated; update them on the device.

While a request is pending, Cancel request withdraws it (Cancel the update request? The agent has not received it yet.). Requests expire after 168 hours (7 days). The section shows Requested by · sent to the agent · last report · expires , and the list reloads every 60 seconds while a request is live. A fleet request adds a summary line such as 12 requested: 3 installing, 5 succeeded, 2 need local opt-in, 2 pending.

Requesting needs agent_updates.create and cancelling agent_updates.delete (Operator and Administrator); seeing requests needs agent_updates.read. Every request, fleet request, cancellation, report and expiry is in the activity log (agent_update.requested, .batch_requested, .cancelled, .reported, .expired).

The API offers GET /api/v1/agents (agents.read; ?outdated=true for outdated Agents only), returning api_key_id, computer_name, agent_version, os, last_seen_at, config_locked, config_locked_since, outdated, latest_version and, with agent_updates.read, update_request; and GET / POST /api/v1/agent-updates ({"api_key_ids": [...]} or {"all_outdated": true}, optional target_version) and DELETE /api/v1/agent-updates/{id} (cancel while pending). A request for an Agent without update-request support is answered 422, or listed under skipped in a fleet request.

Unregistering a device¶

When someone runs the agent's local unregister command (or disconnects from the Windows app's Settings) - 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, shown on the Agents page with the time it happened 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 connected using an existing agent key - either way, the key can only ever flag itself, so there's nothing extra to authorize. The Windows uninstaller's Remove all CertIntel Agent data too? option also unregisters before deleting.

What to do with a flagged device¶

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

• Disable 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; the flag clears automatically.
• Re-register it if the device is in fact still reporting and the flag is stale.
• 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¶