> For the complete documentation index, see [llms.txt](https://docs.keeper.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.keeper.io/keeperpam/endpoint-privilege-manager/custom-tooling/http-reference-guide/health-and-status-endpoints.md). # 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:** ```json { "status": "healthy", "timestamp": "2026-06-30T10:30:00Z", "version": "1.0.0" } ``` **Example:** ```bash 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:** ```json { "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:** ```json { "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:** ```bash 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:** ```json { "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:** ```json { "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:** ```json { "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`. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.keeper.io/keeperpam/endpoint-privilege-manager/custom-tooling/http-reference-guide/health-and-status-endpoints.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.