Retiring & Removing Agents

When a machine is decommissioned, re-imaged, replaced, or compromised, you'll want to take it out of the fleet. Athena gives you two distinct actions for this: revoke the agent — cut off its ability to talk to the server while keeping its record and history — or remove it, which permanently deletes the agent and all of its data. This page explains what each action does, when to use it, and how to do it from the console, the REST API, or PowerShell.

Revoke to lock out, remove to delete

Revoking keeps the agent in Athena but marks it Revoked and invalidates its certificate, so it can no longer authenticate — its inventory, history, and audit trail all stay intact. Removing deletes the agent record and every piece of data attached to it. If you only need the machine to stop connecting, revoke it. If you want it gone entirely, remove it.

Revoke vs. remove#

Both actions require the Admin role. Use this table to pick the right one:

	Revoke	Remove
What it does	Marks the agent Revoked and revokes its certificate(s).	Permanently deletes the agent and all its data.
Can the agent reconnect?	No — the certificate no longer validates and the revoked status is always enforced.	No — there is no record to connect to.
Record kept?	Yes — the agent stays listed with a Revoked status.	No — the agent disappears from the fleet.
Inventory, history & recordings	Retained.	Deleted along with the agent.
Reversible?	The status/record remain, but the machine must re-enroll to rejoin.	No — this cannot be undone.
Role	Admin	Admin
Typical use	Compromised or stolen machine; temporary lock-out; you still need the audit trail.	Retired, re-imaged, or duplicate machine you no longer want in reports.

Just servicing a machine? Use maintenance mode

If the machine is only being patched or rebooted and will stay in the fleet, don't revoke or remove it — put it in maintenance mode instead, which holds it back from commands and deployments without cutting it off. Revoke and remove are for machines you are taking out of service for good.

Revoking an agent#

Revoking an agent sets its status to Revoked and revokes its certificate so it can no longer authenticate to the server. The revoked status is always respected — a revoked agent stays revoked even if it keeps trying to check in — and the certificate itself is marked as revoked, recording why, who did it, and when. The agent record, its inventory, and its history all remain so you keep a complete trail.

In the console, open Agents, find the machine (in the list or on its detail page), and choose the Revoke action. A dialog asks for a reason (at least 3 characters, required); confirm to revoke. The agent immediately shows a Revoked status. The revoke action is hidden for agents that are already revoked.

To revoke via the REST API, post to the certificate-revocation endpoint with a reason. This revokes all of the agent's certificates and sets its status to Revoked:

POST /api/pki/agents/550e8400-e29b-41d4-a716-446655440000/revoke
{
  "reason": "Laptop reported stolen"
}

There is also a lightweight, status-only revoke that flags the agent as Revoked without taking a reason — handy for quick automation where the reason is captured elsewhere:

POST /api/agents/550e8400-e29b-41d4-a716-446655440000/revoke

Revoked certificates stay queryable for the audit trail via GET /api/pki/revoked. For the full certificate lifecycle — issuance, validation, renewal, and revocation reasons — see Certificates & PKI.

Removing an agent#

Removing an agent permanently deletes it. The agent record is dropped and every child record tied to it — inventory, scan history, command and deployment results, compliance evaluations, certificates, and any stored session-recording files — is deleted along with it. This action cannot be undone.

In the console, open Agents, choose the Remove action on the machine, and confirm in the dialog (it shows the machine name, IP, and current status so you can double-check you have the right one). Removal is available from both the agent list and the agent detail page.

Via the REST API, delete the agent by ID:

DELETE /api/agents/550e8400-e29b-41d4-a716-446655440000

Removing is permanent

There is no recycle bin. Once an agent is removed, its inventory and history are gone. If you might still need the record or the audit trail — for example, for a compromised machine under investigation — revoke it instead of removing it. Both actions are written to the audit log either way.

What happens if the machine comes back#

Neither action changes the software on the endpoint — they act on the server side. If a machine whose agent was revoked or removed later tries to connect:

A revoked agent cannot authenticate — its certificate no longer validates — and it stays revoked. To bring the same machine back into service, it must re-enroll with a valid registration token to obtain a fresh certificate.
A removed agent has no record on the server. The machine can be enrolled again from scratch like any new endpoint, which creates a brand-new agent record.

If you are moving an existing agent to a different Athena server rather than retiring it, use Agent Server Migration instead — that preserves the agent rather than revoking or deleting it.

Revoke & remove via PowerShell#

The Athena PowerShell module wraps both actions. Revoke-AthenaAgent flags an agent as Revoked, and Remove-AthenaAgent deletes it. Both take an agent -Id, accept agents from the pipeline, and prompt for confirmation unless you pass -Force (Admin role required):

# Revoke a single agent (prompts for confirmation)
Revoke-AthenaAgent -Id "550e8400-e29b-41d4-a716-446655440000"

# Revoke a compromised machine found by hostname, no prompt
Get-AthenaAgent -Hostname "COMPROMISED-PC" | Revoke-AthenaAgent -Force

# Remove a single agent permanently
Remove-AthenaAgent -Id "550e8400-e29b-41d4-a716-446655440000" -Force

# Clean up agents that have been offline for more than 30 days
Get-AthenaAgent -Status Offline |
  Where-Object { $_.LastHeartbeat -lt (Get-Date).AddDays(-30) } |
  Remove-AthenaAgent -Force

To revoke an agent's certificate with a reason (the equivalent of the console's Revoke dialog), use Revoke-AthenaAgentCertificate — see Certificates & PKI.

Cmdlet	Parameters	Purpose
`Revoke-AthenaAgent`	`-Id` (required, pipeline), `-Force`	Flag an agent as Revoked so it can no longer connect.
`Remove-AthenaAgent`	`-Id` (required, pipeline), `-Force`	Permanently delete an agent and all its data.
`Revoke-AthenaAgentCertificate`	`-AgentId`, `-Reason` (both required), `-Force`	Revoke all of an agent's certificates with a recorded reason.

API & role summary#

Method & path	Role	Purpose
`POST /api/pki/agents/{id}/revoke`	Admin	Revoke all of an agent's certificates with a `reason`; sets status to Revoked.
`POST /api/agents/{id}/revoke`	Admin	Status-only revoke — mark the agent Revoked (no reason body).
`DELETE /api/agents/{id}`	Admin	Permanently delete the agent and all its data.
`GET /api/pki/revoked`	Admin	List revoked certificates for the audit trail.

Auditing#

Both revoke and remove are recorded in the audit log, capturing who performed the action and which machine it affected (certificate revocations also record the reason). This gives you a durable record of when and why machines left the fleet — useful for compliance reviews and incident investigations even after the agent itself is gone.