Skip to main content

API Contracts

OpenAPI lives at specs/openapi.yaml.

Rules:

  • Every API must be tenant-scoped.
  • Every API response shape used by the frontend should be typed or fixture-tested.
  • Auditor endpoints must remain read-only and must not expose mutation controls.
  • API changes require OpenAPI and docs updates in the same branch.

Current API surface supports the unauthorized-device workflow and read paths for alerts, event timelines, evidence, deliveries, delivery attempts, assets, tickets, audit activity, auditor-safe evidence, and the compliance control catalog. Delivery reads expose retry state, next retry time, and attempt timing without exposing credential material.

Asset Discovery v1 read APIs are implemented for asset lists, asset details, asset timelines, collectors, and command history. Enrolled agents can submit runtime-lite heartbeat telemetry through POST /api/v1/agents/{agent_id}/telemetry/heartbeat, which validates the stored agent identity before projecting into asset read models. Collector runtime, osquery/Fleet/OTel ingestion, CA runtime, enforced mTLS, and command execution remain future work.

Discovery authorization APIs have runtime-lite support. They provide tenant/site policy management, service-account authorization grant/deny decisions, redacted observation metadata, and status reads. They do not implement Nmap/SNMP/WMI execution, DHCP/ARP/NetFlow ingestion, topology, or command execution.

Minimal SIEM APIs are contract-only. They define log source registration/status, normalized log search, normalized event detail, and alert linkage. Search is bounded to normalized events and does not add a SIEM query language, search store, or receiver runtime.

Agent enrollment and mTLS identity APIs have runtime-lite support for tenant-admin enrollment-token creation, token revocation, token-for-certificate exchange, agent status reads, and identity-bound heartbeat telemetry. Device certificate rotation and agent revocation remain contract-only. Runtime-lite does not implement a CA, enforced mTLS, or collector bridge.

Internal ticketing and alert triage APIs are implemented for Phase 1. They provide alert acknowledge/assign/resolve on the existing alert model, alert-to-ticket creation, manual ticket creation, ticket list/detail, ticket status/assignment updates, comments, and links. External Jira/ServiceNow/ Freshdesk/Zendesk/HaloPSA adapters remain future outbound integrations.

SCIM provisioning APIs are implemented for the Phase 1 runtime. They provide tenant admin SCIM connection management, deterministic role mappings, service-account user/group provisioning, fail-closed deprovisioning, provisioning status, redacted provisioned-user reads, and a read-only status UI. Entra ID/Okta adapters, standards-shaped /scim/v2 compatibility aliases, real SecretProvider provisioning, broad auth/session rewrite, and writable SCIM UI remain future scoped work.

Auditor export APIs are implemented for the Phase 1 synchronous runtime. They provide export request, list, status, and CSV/PDF artifact reads with every-read audit, metadata/hash, PDF watermark, and server-side redaction. Background export workers, object storage/KMS, signed URLs, and tenant redaction policy editing remain future scoped work.

Compliance policy APIs are implemented for the Phase 1 runtime. They provide policy list/detail, baseline fork, tenant-managed update, and version-history surfaces with optimistic version control, audit, and lifecycle events. Policy editor UI, diff views, bulk operations, and approval workflows remain future scope.

Compliance catalog reads are implemented:

  • GET /api/v1/compliance/frameworks
  • GET /api/v1/compliance/controls
  • GET /api/v1/compliance/controls/{control_id}

These endpoints are tenant-authenticated. Control definitions are global reference data; tenant control status is tenant-owned and protected by Postgres RLS. Control detail responses include tenant-safe linked evidence references without embedding raw evidence payloads.

Browser SSH APIs are contract-only. They define SSH session request, list, and detail surfaces with JIT access, tenant RBAC, timeout, recording, and command log expectations. They do not implement an SSH broker, WebSocket proxy, key vault, recording store, or command execution.

Intune APIs are implemented for Phase 1 posture sync. They provide tenant admin connection configuration, a sync endpoint backed by the Microsoft Graph client abstraction, and redacted device posture reads with SecretProvider credential refs. They do not implement native mobile agents, tenant consent automation, or Intune device-control actions.