Remove Stale Mac Endpoints from the Automox Console

What the stale-Mac-endpoint cleaner does

This Automox Worklet™ removes Mac endpoint records from the Automox console when they have been disconnected longer than a configurable threshold. The Worklet authenticates to the Automox API with an organization token, paginates through the endpoint list, filters for macOS endpoints whose last-check-in timestamp is older than the cutoff, and calls the delete-endpoint API for each match. After the policy run completes, the console inventory reflects the live fleet, not its history.

The Worklet reads two parameters from the policy. The first, ApiToken, is the organization API token from the Automox console settings. The second, MaxDisconnectedDays, is the threshold in days; endpoints whose last check-in is older than (now - MaxDisconnectedDays) are removed. The default is conservative (often 30 days) to avoid removing endpoints that are simply offline for an extended trip or repair window.

Because the API delete operation is irreversible, the evaluation phase runs in report-only mode by default. The script lists the candidate endpoints, prints their hostnames and last-check-in dates to the activity log, and waits for the operations team to flip a second parameter (ConfirmDelete) to true before any record is actually removed. This two-step pattern prevents an over-aggressive threshold from quietly deleting a fleet.

Why prune stale Mac endpoint records

Inventory accuracy is the foundation of every report the Automox console produces. License counts depend on it. Patch compliance percentages depend on it. Policy targeting depends on it. When a laptop is reimaged, decommissioned, or returned at offboarding, the original endpoint record stays in the console forever unless something removes it. Over a year of normal turnover, the inventory can drift 10–20% above the real endpoint count, and every downstream report inherits that drift.

Stale Mac records compound quietly. A retired developer laptop sits in the console for months past its decommission date, a re-imaged Mac joins under a new hostname while the old record persists, and a temporary contractor machine never gets retired after the engagement ends. Run this Worklet on a scheduled cadence to call the Automox API for the Mac inventory, identify endpoints that have not checked in beyond the configured stale-day threshold, and remove them in a single policy pass, so license renewal forecasts, compliance dashboards, and onboarding lifecycle policies use the actual endpoint population. Pair the cleanup with the equivalent Windows and Linux variants for a complete inventory-hygiene loop.

How the Mac endpoint cleanup works

1. Evaluation phase: The Worklet calls GET /servers against the Automox API using the supplied ApiToken, paginates through the full endpoint list, and filters for records where os_family equals macOS or os_name starts with mac. For each matching record, it compares last_disconnect_time to the (now - MaxDisconnectedDays) cutoff. Stale records are collected into a candidate list along with hostname, serial number, and disconnect date. The list is written to the activity log.

2. Remediation phase: If ConfirmDelete is true, the script iterates the candidate list and calls DELETE /servers/{id} against the Automox API for each record. Each delete is logged with the record identifier and the API response status. If ConfirmDelete is false (the safe default), the script reports the candidate list and exits without removing anything, leaving the decision to the operations team.

Mac endpoint cleanup requirements

• macOS endpoint with curl or python3 available to call the Automox API; the Worklet can run from any Mac in the fleet because the work is API-side, not endpoint-local

• Automox organization API token with permission to list and delete endpoints; do not reuse a personal token, because revoking it later breaks the policy

• ApiToken and MaxDisconnectedDays parameters set in the policy; default MaxDisconnectedDays is 30, raise it if the fleet routinely has long offline periods

• ConfirmDelete kept at false until the operations team has reviewed the first candidate report and approved the deletion threshold for production runs

• Backup or SIEM export of the candidate list before each production run, so a record exists of which endpoints were removed on which date

Expected console state after cleanup

After a production run with ConfirmDelete set to true, the Automox console no longer lists the stale Mac endpoint records that were removed. Subsequent license-count reports, patch-compliance dashboards, and policy-targeting queries reflect the real macOS fleet size. New endpoints that check in after a long offline period reappear in the console with a new endpoint identifier; the old identifier does not return.

Validate by capturing the endpoint count from the Automox console before the policy run, running the Worklet in report-only mode, comparing the candidate list to your offboarding records, then re-running with ConfirmDelete true. For audit evidence, export the activity log entries showing the API response for each delete call and store them with the policy run identifier. A regression where the inventory bloats again over time is normal; the Worklet is designed to run on a recurring schedule (monthly is a common choice) rather than as a one-time cleanup.