Developer Portal

EdgeHub API Documentation

EdgeHub is a high-performance telemetry and observability platform designed to monitor distributed edge devices, virtual machines, and containerised workloads. The Control Plane exposes secure, asynchronous REST endpoints for node provisioning, real-time telemetry ingestion, zero-downtime token rotation, and edge fleet management.

Node Provisioning

Manage the full agent lifecycle — secure JWT generation, single-use registration tokens, and instant revocation.

Telemetry Ingestion

Optimised endpoints for high-throughput ingestion of hardware metrics, Docker container states and Kubernetes pod health.

Security First

Every route requires authentication. Admin API Keys for control-plane operations; strictly validated JWTs for edge nodes.

Smart Alerting

Buffered state evaluation with configurable thresholds prevents false positives. Discord and Slack webhooks supported.

System Architecture

The platform operates on a strictly decoupled client-server architecture divided into a Control Plane and a Data Plane.

Control Plane — Backend

A robust, asynchronous REST API built with Python (FastAPI) and PostgreSQL. Serves as the central hub for node provisioning, secure agent authentication and data ingestion.

Hybrid Data Schema: Core metrics (CPU, RAM, Disk, Uptime) adhere to a strict relational schema for high-performance querying. An extensible JSON column dynamically captures environment-specific telemetry (Docker, Kubernetes) without requiring database migrations.

Data Plane — Agent

A self-contained, multi-architecture Go binary (AMD64 & ARM64). Statically compiled with all dependencies bundled — no runtime installation required on the target node. It auto-detects its environment and operates on a push-based telemetry loop with a minimal resource footprint.

Request Lifecycle

1 · Provisioning & Authentication

Admin ─────────────▶ POST /auth/login // Admin credentials

API ◀───────────── 200 OK // Set-Cookie: Session

Admin ─────────────▶ POST /sites // Create Site/Group

Admin ─────────────▶ POST /nodes/token // Generate registration token

API ◀───────────── 201 Created // Returns one-time token

2 · Agent Initialization & Registration

Agent ────────────── Check local edgehub-state.json → not found

Agent ─────────────▶ POST /agents/register // Payload + token

API ────────────── Validate token, burn it (single-use), create node

API ◀───────────── 201 Created // Returns Node ID + JWT

Agent ────────────── Save JWT to edgehub-state.json

3 · Continuous Telemetry & C2 Loop

Agent ────────────── Collect base & extra metrics (Docker / K8s)

Agent ─────────────▶ POST /agents/heartbeat // Bearer JWT

API ◀───────────── 200 OK // Update last_seen, return pending C2 commands

Agent ────────────── Execute commands (e.g. rotate token) and update local state

4 · Security & Revocation

Admin ─────────────▶ DELETE /nodes/:id // Revoke / delete node

API ────────────── Mark node deleted, invalidate JWT

Agent ─────────────▶ POST /agents/heartbeat

API ◀───────────── 401 Unauthorized

Agent ────────────── os.Exit → halts immediately, state file retained

Backend Deployment

The recommended method to deploy EdgeHub is via the interactive installation script. It orchestrates FastAPI, PostgreSQL, and Nginx as isolated Docker Compose services.

Run the command below on your master server. The script will interactively prompt you for configuration values (domain name, CORS origins, credentials) and set everything up automatically.

bash — quick install
curl -sSL https://raw.githubusercontent.com/AndreaProzzo21/edge-hub/main/edge-hub-app/scripts/install.sh | sudo bash

What the script provisions

FastAPI Application Container

The core REST API and websocket server running the Control Plane logic — node management, token issuance, telemetry ingestion, and alert dispatch.

PostgreSQL Database

Stores node entities, registration tokens (single-use, burned on consumption), telemetry time-series, site configurations, and webhook targets.

Nginx Reverse Proxy

Handles static asset delivery, request routing to FastAPI, and built-in Leaky Bucket rate limiting on critical endpoints (login, heartbeat).

Web Dashboard

The management UI for provisioning nodes, generating registration tokens, monitoring fleet telemetry, configuring webhooks, and reviewing alerts. Exposed on port 80 by default.

The Control Plane exposes port 80 (HTTP) out of the box. Do not expose this port directly to the internet without placing a TLS-terminating reverse proxy or secure tunnel in front of it first.

Security Configuration

EdgeHub follows a Bring Your Own Reverse Proxy philosophy. These requirements must be satisfied before exposing the platform to the internet.

SSL / TLS Termination

Route traffic through Cloudflare Tunnels, Nginx Proxy Manager, Traefik, or Caddy for HTTPS. Never expose port 80 directly.

CORS Origins

During installation, provide your Dashboard URL. This sets CORS_ORIGINS — browser requests from any other domain are rejected by the API.

Rate Limiting

The built-in Nginx container applies Leaky Bucket rate limiting to login and heartbeat endpoints, protecting against brute-force and malfunctioning agents.

Single-Use Tokens

Registration tokens are cryptographically generated and burned immediately upon first use. An agent cannot register twice with the same token.

Instant Revocation

Deleting a node via the dashboard immediately invalidates its JWT on the backend. The agent exits on its next heartbeat cycle and does not attempt to re-register.

Auth Hierarchy

Admin API Keys gate all control-plane operations. Edge node JWTs are strictly scoped — they may only submit heartbeats, nothing more.

Zero-Downtime Rotation

Agent JWTs are rotated seamlessly using a Rolling JTI mechanism. Old tokens remain valid just until the new token is acknowledged by the agent.

Unidirectional C2

Agents poll for commands via heartbeats. No inbound ports need to be opened on the edge firewall, ensuring strict NAT compatibility. The only command currently supported is update_jwt, which triggers a secure, atomic rotation of the agent's authentication token. This design ensures that the Control Plane cannot execute arbitrary tasks, maintaining a strictly limited and secure operation profile.

Deploying Agents

Agent deployment is managed from the EdgeHub Dashboard. Log in, generate a registration token for the target site, and use the pre-configured copy-paste commands.

The dashboard auto-fills the correct API endpoint URL and registration token into each deployment command. You never need to manually construct these.

The only case where you need to copy a new token and re-inject it as an environment variable — then restart the process, container, or deploy — is when a Node JWT has fully expired and disconnected. The agent will have received a 401 response and shut down.

Linux Native (Systemd)

Executed as a root-level background daemon. Designed for bare-metal servers, virtual machines, and IoT devices such as Raspberry Pi.

Reads hardware metrics directly from the Linux kernel. Automatically registers as a systemd service for auto-start on reboot.

Docker Compose

Runs as an isolated container. Binds to the host Docker socket to enumerate container states, and mounts host system volumes read-only to accurately calculate underlying hardware utilisation.

Kubernetes

Deploy one agent as a standard Deployment on a single node with RBAC and hostNetwork/hostPID configurations to interface with the cluster API and report pod health.

For remaining worker/master nodes, deploy the Linux Native agent for basic telemetry and heartbeats.

Agent Lifecycle & Authentication

The agent operates a well-defined state machine from first-boot registration through continuous telemetry to eventual revocation.

Boot & State Check

On startup the agent checks for edgehub-state.json in the local filesystem. If found (and the JWT therein is valid), it skips registration entirely and jumps directly to the telemetry loop.

First-Time Registration

If no state file exists, the agent calls POST /api/v1/agents/register with the provisioning token and hardware metadata. The backend validates and burns the token (single-use), creates the node entity, and returns a persistent JWT.

JWT Persistence

The returned JWT is written to edgehub-state.json. On subsequent restarts (updates, reboots, container restarts) the agent loads this file and resumes without re-registering.

Continuous Heartbeat & C2

Every N seconds the agent collects base metrics (CPU, RAM, disk, uptime) plus environment-specific data (Docker container states or Kubernetes pod health) and posts them to POST /api/v1/agents/heartbeat with a Bearer JWT. The response includes any pending Command & Control instructions.

Zero-Downtime Token Rotation

Administrators can queue a JWT renewal via the backend. The agent retrieves the new token during its next heartbeat, seamlessly updates its local edgehub-state.json, and transitions to the new cryptographic identity without downtime.

Revocation & Shutdown

If the backend returns 401 Unauthorized, the agent exits immediately via os.Exit. The edgehub-state.json file is intentionally retained on disk — this prevents the agent from attempting to re-register with an already-consumed registration token on its next start. Re-provisioning requires an admin to generate a new token, update the environment variable on the node, delete the state file manually, and restart the service.

Alerting & State Management

Third-party webhooks (Discord, Slack) can be configured at the Site level. EdgeHub implements a buffered evaluation mechanism to prevent false positives from transient network instability.

Node Online — Normal Operation

Heartbeat received on schedule. Backend updates last_seen, resets offline_cycles counter to 0. No notifications triggered.

Missed Heartbeat — Failing State

A scheduled heartbeat does not arrive. The backend increments offline_cycles. The node enters a failing state internally, but no webhook is triggered yet. Transient network blips are absorbed here.

3 Consecutive Misses — Offline Alert

After three consecutive missed cycles the backend transitions the node to offline and dispatches the configured webhook payloads (Discord embed, Slack block-kit message, or generic JSON).

Heartbeat Resumes — Recovery Notification

A successful heartbeat from a previously-offline node immediately resets all failure counters and dispatches a recovery notification through the same webhook channels.

Telemetry Retention & Cleanup

EdgeHub automatically purges historical heartbeat records to keep the database lean and prevent unbounded growth over time.

Automatic Daily Cleanup

A background async task runs every 24 hours and permanently deletes all heartbeat records older than the configured retention window. The task operates entirely within the database layer — no external scheduler or cron job is required.

On each run the backend logs how many records were removed, making it easy to track growth trends over time.

Configurable Retention Window

The default retention period is 7 days. This is sufficient for trend analysis and incident review in most edge deployments, while keeping storage requirements predictable.

The retention window is controlled by the HEARTBEAT_RETENTION_DAYS environmental variable passed to the cleanup task at startup. Adjust it to suit your storage capacity and observability requirements.

Only raw heartbeat records are subject to automatic deletion. Node entities, site configurations, registration tokens, and alert history are never touched by the cleanup task — they persist until explicitly removed via the dashboard or API.

If you need more than 7 days of telemetry history — for example, for capacity planning or long-term trend analysis — increase HEARTBEAT_RETENTION_DAYS before deploying. Records deleted by the cleanup task are not recoverable.

API Authentication

All routes require authentication. Two credential types are in use depending on the caller identity.

Credential	Used By	Mechanism	Scope
Admin API Key	Dashboard / Operators	Session cookie set after `POST /auth/login`	Full control-plane access: create/delete nodes, generate tokens, configure webhooks, view telemetry
Node JWT	Edge Agents	`Authorization: Bearer <jwt>` header	Submit heartbeats only (`POST /agents/heartbeat`). Cannot access any other endpoint.
Registration Token	Agent (first boot only)	Request body field during registration	One-time use. Burned on consumption. Produces a Node JWT.

Data Schema

EdgeHub uses a hybrid relational + JSON schema for telemetry. Core metrics are strictly typed columns; environment-specific extras live in a JSON column.

Strict Relational (Core)

cpu_percent ram_percent disk_percent uptime_seconds last_seen node_id

Indexed columns enabling high-performance aggregation queries across the entire fleet — average CPU across a site, nodes above memory threshold, etc.

Dynamic JSON Column (Extras)

docker.containers docker.running k8s.pods k8s.node_status

Captures environment-specific data without schema migrations. New telemetry fields in future agent versions are automatically stored without any backend changes.

See the full interactive API reference below for complete request/response schemas, field-level validation rules, and example payloads for every endpoint.

Interactive API Reference

Auto-generated from openapi.json — all endpoints, schemas, and example payloads.

OpenAPI 3.0