Health & Status Endpoints

Keeper EPM exposes a set of built-in HTTP endpoints for checking service liveness, plugin status, and overall system health. Use these endpoints with your existing monitoring tools — load balancers, uptime probes, SIEM agents, or custom automation — to confirm the agent is running and operating as expected on each endpoint.

All endpoints are served by the local KeeperPrivilegeManager service on https://localhost:6889 (HTTPS) or http://localhost:6888 (HTTP) and are bound to localhost only. The agent's control plane is never exposed on the network.

Public Endpoints

These endpoints require no authentication and can be called by any process on the endpoint. They are appropriate for monitoring systems, load balancer probes, and basic automation.

Service Liveness

GET /health

Returns 200 OK if the service is running. This endpoint bypasses all middleware, making it the lightest-weight check available and the recommended choice for high-frequency liveness probes.

Response:

{
  "status": "healthy",
  "timestamp": "2026-06-30T10:30:00Z",
  "version": "1.0.0"
}

Example:

curl -k https://localhost:6889/health

Service Information

GET /

Returns basic service identification. Useful as a smoke test to confirm the correct service is responding on the expected port.

Response:

{
  "service": "Keeper Privilege Manager",
  "status": "running",
  "version": "1.0.0"
}

System Status

GET /api/system/status

Returns aggregate status for the service, including plugin and job counts. Use this endpoint when you want a single call that summarizes whether the agent is fully operational, not just running.

Response:

{
  "serviceName": "Keeper Privilege Manager",
  "status": "running",
  "timestamp": "2026-06-30T10:30:00Z",
  "uptimeSeconds": 3600.0,
  "activePlugins": 5,
  "plugins": {
    "total": 6,
    "running": 5
  },
  "jobs": {
    "total": 10,
    "enabled": 8
  }
}

Example:

curl -k https://localhost:6889/api/system/status

Privileged Endpoints

These endpoints return detailed plugin and monitoring data and require either Plugin-level or Admin-level authorization. Calls must originate from a process launched by Keeper EPM or from an elevated context (Administrator on Windows, sudo on Linux/macOS).

Plugin Status

GET /api/plugins

Returns the status of every plugin known to the service, including process ID and last start time. Use this endpoint to identify which plugins are stopped, failed, or missing.

Authorization: Plugin

Response:

{
  "plugins": [
    {
      "id": "KeeperPolicy",
      "name": "Keeper Policy Plugin",
      "status": "Running",
      "processId": 12345,
      "lastStartTime": "2026-06-30T10:00:00Z"
    }
  ],
  "count": 6
}

Plugin Health Detail

GET /api/monitoring/plugins

Returns detailed health information for each monitored plugin, including health status (Healthy, Unhealthy, Starting, Stopping, Failed), process ID, and uptime. This is the endpoint to use when you need to alert on plugin health specifically rather than process existence.

Authorization: Plugin

Response:

{
  "plugins": [
    {
      "id": "KeeperPolicy",
      "status": "Healthy",
      "processId": 12345,
      "lastStartTime": "2026-06-30T10:00:00Z",
      "uptime": "2h 30m"
    }
  ]
}

Plugin Monitoring Service Status

GET /api/monitoring/status

Returns the status of the plugin monitoring service itself, including the configured check interval, the time of the last check, and which plugins are currently being monitored.

Authorization: Plugin

Response:

{
  "monitoringEnabled": true,
  "status": "Active",
  "details": {
    "isRunning": true,
    "checkIntervalMinutes": 0.5,
    "lastCheckTime": "2026-06-30T10:30:00Z",
    "totalPlugins": 6,
    "monitoredPlugins": 5,
    "monitoredPluginIds": ["KeeperPolicy", "KeeperApi", "KeeperLogger"]
  },
  "timestamp": "2026-06-30T10:30:00Z"
}

Service and Plugin Health Behavior

Beyond the endpoints above, Keeper EPM includes built-in self-monitoring and automatic recovery:

• Plugin monitoring loop: The service checks plugin process existence and responsiveness every 30 seconds by default. The interval is configurable via the PluginMonitoring.CheckIntervalMinutes setting.
• Automatic plugin restart: Plugins configured for auto-restart are relaunched automatically when the monitoring loop detects they have failed or become unresponsive.
• Automatic service recovery: The KeeperPrivilegeManager service is configured to restart on failure by the operating system — Service Control Manager on Windows (15-second delay, up to 10 attempts), systemd on Linux (Restart=on-failure, 15-second delay), and launchd on macOS.

These behaviors mean that transient plugin failures usually resolve without admin intervention, but they also mean a plugin that appears "Running" via /api/plugins may have been restarted recently. For incident investigation, correlate the lastStartTime field with your log data — see Reading Logs for guidance.

Recommended Monitoring Patterns

Basic liveness: Poll GET /health every 1–5 minutes from your monitoring system. Alert on any non-200 response.

Operational health: Poll GET /api/system/status every 5 minutes. Alert when plugins.running is less than plugins.total, or when the response cannot be parsed.

Plugin-level alerting: Poll GET /api/monitoring/plugins from a privileged context (a Keeper-launched job, or an elevated scheduled task) every 5–15 minutes. Alert on any plugin reporting a status other than Healthy.

Load balancer probes: Use GET /health exclusively. The endpoint bypasses middleware and is the only one designed for high-frequency, low-overhead probing.

Authentication Notes

The public endpoints (/health, /, /api/system/status) require no authentication and can be called from any process on the endpoint, including unprivileged user contexts.

The privileged endpoints use process-based authentication. A call succeeds when the calling process is either:

• A process launched by Keeper EPM and tracked in its internal process registry, or
• A process running with administrator privileges (Run as administrator on Windows, sudo on Linux/macOS).

A curl command from a non-elevated terminal will receive 401 Unauthorized from the privileged endpoints. For ad-hoc troubleshooting, run the terminal as administrator or use sudo.