Agent APIs

REST API reference for agent-to-server communication — enrollment, heartbeat, policy, alerts, commands.

Base URL

https://your-server:5100/api/v1

All endpoints except /enroll require X-API-Key and X-Device-ID headers.

---

POST /enroll

Authentication: Enrollment token (no API key required)

Request:

json

{
  "enrollment_token": "abc123...",
  "hostname": "LAPTOP-JOHN",
  "os": "Windows",
  "os_version": "Windows 11 Pro 22H2",
  "device_model": "Dell Latitude 5540",
  "serial_number": "ABC123XYZ",
  "mac_address": "00:1A:2B:3C:4D:5E",
  "agent_version": "1.0.0"
}

Response (201):

json

{
  "device_id": "uuid-here",
  "api_key": "generated-48-byte-urlsafe-token",
  "tenant_id": "tenant-uuid",
  "policy": { "...full policy JSON..." },
  "policy_version": 1
}

Errors:

400 — Invalid or missing enrollment token
409 — Device already enrolled (duplicate serial number)
403 — Token expired or max uses reached

---

POST /heartbeat

Send device status update and check for policy changes or pending commands.

Headers: X-API-Key, X-Device-ID, X-Agent-Version

Request:

json

{
  "status": "active",
  "guards_status": {
    "usb_guard": true,
    "network_guard": true,
    "browser_guard": true,
    "process_guard": true,
    "clipboard_guard": true,
    "screenshot_guard": true,
    "file_watcher": true,
    "airdrop_bt_guard": true,
    "print_guard": true,
    "encryption_guard": true
  },
  "policy_version": 3,
  "hostname": "LAPTOP-JOHN",
  "username": "john.doe",
  "ip_address": "192.168.1.100"
}

Response (200):

json

{
  "status": "ok",
  "policy_version": 4,
  "needs_policy_update": true,
  "pending_commands": [
    {
      "id": "cmd-uuid",
      "command": "collect_status",
      "payload": {}
    }
  ]
}

---

GET /policy/{device_id}

Fetch the effective policy for this device (with exceptions merged).

Response (200):

json

{
  "policy": {
    "usb_guard": { "enabled": true, "mode": "block", "auto_eject": true, "whitelist": [] },
    "network_guard": { "enabled": true, "mode": "block", "blocked_ports": [21,22,23] },
    "browser_guard": { "enabled": true, "mode": "block", "blocked_domains": ["..."] },
    "...other guards..."
  },
  "version": 4,
  "policy_id": "policy-uuid"
}

The policy is resolved with 3-level priority: device override → group (parent chain) → tenant default. Active UserException records are merged into the response.

---

POST /alerts

Submit security alerts in batch.

Request:

json

{
  "alerts": [
    {
      "guard": "usb_guard",
      "severity": "CRITICAL",
      "message": "USB storage device blocked",
      "details": {
        "vendor_id": "0x1234",
        "product_id": "0x5678",
        "serial": "ABC123",
        "action": "blocked_and_ejected"
      },
      "timestamp": "2026-08-17T10:30:00Z"
    }
  ]
}

Response (200):

json

{
  "status": "ok",
  "received": 1
}

Limits: Maximum 200 alerts per API call. The agent batches alerts and sends up to 50 per push cycle.

---

GET /commands/{device_id}

Fetch pending commands for this device. Commands are marked as delivered once fetched.

Response (200):

json

{
  "commands": [
    {
      "id": "cmd-uuid",
      "command": "update_policy",
      "payload": {},
      "created_at": "2026-08-17T10:00:00Z"
    }
  ]
}

---

PUT /commands/{cmd_id}/ack

Acknowledge command execution.

Request:

json

{
  "status": "executed",
  "result": { "message": "Policy updated successfully" }
}

Status values: executed or failed

---

POST /recovery-key

Store an encrypted disk recovery key.

Request:

json

{
  "key_type": "bitlocker",
  "encrypted_key": "base64-encoded-aes-encrypted-key",
  "algorithm": "AES-256"
}

Response (201):

json

{
  "status": "stored",
  "key_id": "uuid"
}

Previous recovery keys for the same device are marked as is_current = false (key rotation).