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 (New agent at the top of the Agents page goes there too). Every organization already has a token; its row shows only the token's prefix (cit_xxxx…) with Show, Install commands, Rotate and Revoke buttons. The list itself has no install command. Click Install commands (or Show, or the row) to open the token's own page; 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 default) is for a terminal on the server, as when you paste the command yourself. It asks only when it needs an answer: on Windows whether to keep or remove an earlier installation's data, on Linux whether to install missing system packages, and on both to type REMOVE before Reset existing data deletes anything; on Windows the installer also shows its window. Silent asks nothing and opens no window, so it needs no terminal: use it for scripts, RMM tools and other automation. It keeps an earlier installation's data (unless Reset existing data is ticked, which then deletes it without asking) and installs missing Linux system packages. The commands carry the token, so neither mode asks for it.
   • API base: where agents connect to this CertIntel deployment. The field is pre-filled with this deployment's agent address (https://api.certin.tel on the hosted service; your own ingest or workspace address on another deployment), so leave it as it is. Enter an HTTPS origin only: letters, digits, dots and hyphens, or a bracketed IPv6 address, with an optional port, and no path or trailing slash. Anything else disables the copy buttons with Enter an HTTPS origin like https://api.certin.tel (no path or trailing slash). Whenever the address differs from https://api.certin.tel, every command passes it to the installer (-ApiBase '…' on Windows, --api-base '…' on Linux), so a command pasted as shown enrolls against this deployment.
   • 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.
   • Default settings lists what a new installation does when you choose no option, each with Yes or No: it checks for agent updates every 24 hours (Yes), installs verified updates automatically at that check (No), installs an update when a CertIntel administrator asks for it (Yes; Agent 1.17.0+), checks internal endpoints assigned by CertIntel every 60 minutes (Yes) and applies dashboard assignments from this organization without local approval (Yes; a new installation of Agent 1.8.1 or later). It also names the intervals: the Agent monitor every 24 hours and the renewal check every 720 minutes. Every one of them can be changed under Advanced, and later on the device.
   • Advanced, closed until you open it (opening it changes nothing in the commands), holds the rarely needed options:
     • 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.
     • Agent settings: Check for agent updates, Install verified updates automatically (the Agent's own scheduled check), Allow update requests from CertIntel (Agent 1.17.0+; an older installer refuses the option), Agent monitor interval, hours (1–720), Check internal endpoints assigned by CertIntel, Assigned endpoint check interval, minutes (5–1440), Renewal check interval, minutes (1–1440) and Apply dashboard assignments from this organization without local approval. Each switch starts at Installer default (On) or Installer default (Off), which names what the Agent does by itself and adds nothing to the commands. The last one reads Installer default (on for a new installation): a new installation turns it on once it is connected, bound to this organization, so the organization's dashboard assignments are applied without a local approval. Choose Off to keep a local administrator's approval on the server for every dashboard assignment (certintel assignments approve). Upgrading an existing installation keeps its current choice unless you choose On or Off. It can be changed later on the server with certintel assignments policy --auto-apply on or off. A changed setting adds -InstallOption NAME=VALUE to the Windows commands and --agent-setting key=value to the Linux command (see Windows Agent and Linux Agent). A number outside its range disables the copy buttons with, for example, Agent monitor interval, hours: enter a whole number from 1 to 720, or leave it empty for the installer default.
3. Still on the token page, click Copy commands under PowerShell (elevated), cmd.exe (elevated) or Bash, and run it on the device.

4. The page's After the command section says what comes next: the computer waits for approval on the Agents page, and Get a certificate for a server continues from there (it also lists the computer for approval). The installer itself ends with the same advice:

   Next: approve this computer (web01) on the Agents page of your CertIntel dashboard:
     https://app.certin.tel/all-hosts
   Until then it is "pending approval": it cannot report or receive certificates.
   Then choose "Get a certificate for a server" on the dashboard Overview.
   

   On another CertIntel deployment the first line points at the dashboard that gave you the command and names the address the computer connects to.

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.

The exchange works only on an address that serves your workspace's agents. On the platform console's host, on another workspace's address, or - when your workspace accepts agents only on its own address - on any other host, it is refused with 404 before a key is created or a one-time token is used: This host does not serve CertIntel agents. Enroll against https://… (installer option --api-base https://… / -ApiBase https://…). The install token was not used. Run the installer again with the address it names.

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¶

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¶

Above the tokens, the list shows the API base the install commands use, read-only, with Copy API base: where agents connect to this CertIntel deployment, and the value an automated install needs too. It is not a secret, so it needs no Show.

The list opens on the Organization tokens tab: the long-lived tokens, one per organization. One-time tokens lists the one-time tokens and All both kinds; each tab shows how many tokens it holds, so a one-time token you just minted is one click away. Sorting stays on the tab you are on, and so does an action such as Revoke.

Every tab has 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 commands, 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 on the One-time tokens and All tabs 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 Install commands) 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. The Agent also records one approval-pending event in Activity, reports approval_pending: true in certintel status --json and logs approval-granted once it notices 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.

Approval is also where the plan's Agents limit applies. Pending agents do not count, so installing and exchanging a token always succeeds; if approving this agent would go over the limit, the approval is refused with Tenant subscription limit reached for agents (N). Existing resources are preserved; remove a resource or upgrade the plan. and the agent stays pending. The page shows a warning when approving every pending agent would exceed the plan. Revoking, deleting or unregistering an agent frees its slot; see Plans, pricing and limits.

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 Waiting for first heartbeat, and its tooltip says Approved – waiting for first heartbeat. Agent 1.8.0+ notices its approval within seconds and reports at once. Older agents ask once a minute for 15 minutes after connecting, then every 15 minutes; restart the CertIntel Agent service to make them ask now. (see Agent states at a glance); 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 (Install on Linux with the Linux section and its command first), and the one-time token form under Installing by hand? Mint a one-time install token … (see Minting a one-time token).

While an agent approved in the last 30 minutes has not reported yet, the Agents page reloads itself every 15 seconds while it is shown (it stops once you start filling in a form on it, so nothing you typed is lost) and the row adds (this page checks again by itself), so the row menu's Workflows entry appears without a manual reload once the agent has reported. After those 30 minutes, reload the page once the agent has reported.

The Agents page¶

Each row shows the device, its OS (Windows, Linux or macOS), the agent version, the API key prefix, organization, roles, Reporting state and credential state. Details opens the device's reporting history. A failed check-in of an Agent run that the Agent then completed on a retry without a check-in of its own (a failed installation it retried) reads recovered - failed at first, succeeded on retry … - with View renewal. The Agent also sends a heartbeat (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. The Reporting column says whether it is: Reporting; Late when two hourly reports are missing (Last report 3 h ago, expected every hour); Offline after 24 hours without a report (Offline since … (26 h)), when its certificates are not renewed or reported until it is back and the Agents that stopped reporting alert lists it. An Agent whose key cannot report is never Late or Offline: it shows the reason - Disabled, Expired or Pending approval in the list (an unregistered key reads unregistered …), Unregistered on its page - and that it is not counted as late or offline. The Reporting filter offers Reporting, Late (missed 2 hourly reports), Offline (no report for 24 hours), Late or offline, Never reported and Offline or never reported (what the Clients page counts as an offline agent); it counts only approved, unexpired, enabled agent credentials and leaves out paused hosts.

The device's details show Last report - when the Agent last contacted CertIntel, with its hourly heartbeat or any report - and Last renewal run reported - when it last reported the outcome of issuing or renewing a certificate. That happens only when a certificate is issued or renewed, so it is often days or weeks old and does not show whether the Agent is running. A late or offline Agent's details also say what to check on the device; see An Agent shows Late or Offline.

A Locked pill on the row 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.

The device's detail also has:

• Detected on this server - the servers on the computer that use a certificate, as the Agent's read-only server detection reported them: the kind of server and port, the names, the certificate in use and its expiry, whether a proposal already covers the names, and Create workflow. It appears only for an Agent that sent the report. See Detected servers.
• Failing certificates - certificates whose last issuance, renewal or installation failed, with what the Agent does next by itself (the time of its next try, or Stopped retrying) and the command that tries now on the device. See When the Agent tries again.

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 (as the Agent reports it), its sealing key with its fingerprint, Approve key … for the first key it reports and Approve new key … when it reports a new one (each names the key id).
• Private CA roots - whether the machine trusts each Private CA root, per trust store.

Agent updates from the dashboard¶

On a platform build that offers the feature, an Update available <version> 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 (<version>)) lists only those Agents.

Update now (on the host detail page's Agent update section, and on each row) and Update all outdated (<n>) (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 (Agent 1.13.0+: within about a minute).
• 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.
• An Agent 1.17.0 or later installs it unless Allow update requests from CertIntel is turned off on the device; then it refuses with update requests are turned off on the device. The setting is on by default and separate from Install verified updates automatically, the Agent's own scheduled check, which a request does not need. See Windows updates and Linux updates.
• An Agent before 1.17.0 installs it only when a local administrator turned automatic installation on; otherwise it refuses with automatic installation is off on the device; agents before 1.17.0 need it on for update requests.
• The confirmation and the note on the Agent's page name the rule of that Agent's release. A refusal says what turns the setting on. A request the Agent refused stays refused, so request the update again after changing the setting.
• The configuration lock does not block signed updates.
• Linux Agents before 1.12.1 always refuse (automatic installation is not available in this release); update them once on the device with sudo certintel update install, or with apt or dnf for package installs.

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 <time> by <user> · sent to the agent <age> · last report <age> · expires <time>, 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 turned off on the device, 2 pending, with one line beneath it for each reason that says what to do.

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 sets the unregistered flag, shown on the Agents page with the time it happened instead of a misleadingly-fresh "last seen" timestamp. From then on the key stops working: every request with it is refused with the same 401 as a revoked key, also if the same secret is restored from a backup. The device said it discarded the key, so the key no longer takes a slot of the plan's Agents limit. The key itself is not deleted: an administrator can bring it back with Re-register (same secret) or Rotate (new secret), each subject to the plan's Agents limit.

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. Only agent keys can unregister: an integration key is refused (403), because it takes no agent slot and flagging a shared key would switch it off for its other users; the agent drops its local copy whatever the answer. The Windows uninstaller's Remove all CertIntel Agent data too? option also unregisters before deleting.

What to do with a flagged device¶

An unregistered key no longer works, but it stays on the Agents page. From there:

• Disable or Delete 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 and the device connects with the new secret.
• Re-register it if the device still has the same key and should keep using it.
• Leave it if you're not sure yet - it takes no slot of the plan's Agents limit while it is unregistered, and the badge keeps it visible until you decide.

Agent states at a glance¶