Documentation > API > Federation

Federation API

Endpoint reference for federating multiple SysManage servers. The open-source core ships the identity surface (key exchange, certificate pinning, role selection) so peers can establish trust. The substantive coordinator and site surfaces are Professional+ features implemented in the licensed federation engines; when those engines are not loaded the routes are mounted as stubs that report they are unlicensed. All coordinator/site endpoints require Bearer-token auth except enrollment completion and the site-to-coordinator ingest endpoints, which authenticate with a site token instead.

Identity and Role (Open Source)

The identity surface is thin and lives in the OSS core. It handles key exchange between peers, exposes the federation TLS certificate for pinning (unauthenticated, since it is public), and lets an operator select this server's federation role. The valid roles are none, coordinator, and site.

  • GET /api/v1/federation/identity-key — this server's federation public identity key and fingerprint
  • GET /api/v1/federation/trusted-peers — list trusted federation peer keys
  • POST /api/v1/federation/trusted-peers — import a peer's public key into the trusted keyring
  • DELETE /api/v1/federation/trusted-peers/{name} — remove a trusted peer key
  • GET /api/v1/federation/tls-cert — this server's federation TLS certificate (unauthenticated, public)
  • GET /api/v1/federation-role / PUT /api/v1/federation-role — read or set the federation role

Coordinator: Sites Registry (Pro+)

The coordinator enrolls and manages the sites it federates. Enrollment completion is token-authenticated so a new site can finish the handshake before it holds operator credentials.

  • GET /api/v1/federation/sites / POST /api/v1/federation/sites — list or enroll federation sites
  • POST /api/v1/federation/sites/enrollment/{token}/complete — complete the enrollment handshake (token-authenticated)
  • GET /api/v1/federation/sites/{site_id} / PATCH — get or update a site
  • POST /api/v1/federation/sites/{site_id}/suspend / resume — suspend or resume a site
  • DELETE /api/v1/federation/sites/{site_id} — remove a site
  • GET /api/v1/federation/sites/{site_id}/sync-status — site sync status
  • GET /api/v1/federation/sites/{site_id}/sync-timeline — site sync event timeline
  • POST /api/v1/federation/sites/{site_id}/repush-policies — repush policies to a site

Coordinator: Host Directory and Rollups (Pro+)

Cross-site visibility. The host directory searches hosts across all federated sites; the rollups aggregate host, compliance, and vulnerability data into coordinator-level dashboards and reports.

  • GET /api/v1/federation/hosts — search hosts across federation sites
  • GET /api/v1/federation/hosts/{host_id} — host details from the federated directory
  • GET /api/v1/federation/rollups/dashboard — rollup dashboard data
  • GET /api/v1/federation/reports/rollup — rollup report
  • GET /api/v1/federation/rollups/hosts — host rollups across sites
  • GET /api/v1/federation/rollups/compliance — compliance rollups across sites
  • GET /api/v1/federation/rollups/vulnerabilities — vulnerability rollups across sites

Coordinator: Policies and Commands (Pro+)

Policies are authored at the coordinator, assigned to sites, and pushed out. Commands are dispatched to sites and tracked centrally.

  • GET /api/v1/federation/policies / POST — list or create policies
  • GET /api/v1/federation/policies/{policy_id} / PATCH / DELETE — get, update, or deactivate a policy
  • POST /api/v1/federation/policies/{policy_id}/assign — assign a policy to sites
  • POST /api/v1/federation/policies/{policy_id}/push — push a policy to enrolled sites
  • POST /api/v1/federation/commands/dispatch — dispatch a command to sites
  • GET /api/v1/federation/commands — list dispatched commands
  • GET /api/v1/federation/commands/{command_id} — command details

Coordinator: Audit, Alerts, and Secret Leases (Pro+)

Cross-site audit log, rollup alerting with acknowledgement and configuration, and the federation-aware view of dynamic secret leases.

  • GET /api/v1/federation/audit — list federation audit entries
  • GET /api/v1/federation/audit/{entry_id} — audit entry details
  • GET /api/v1/federation/alerts — list rollup alerts
  • POST /api/v1/federation/alerts/{alert_id}/acknowledge — acknowledge an alert
  • GET /api/v1/federation/alert-config / PUT — read or update alert configuration
  • GET /api/v1/federation/secret-leases — list federation-aware secret leases
  • POST /api/v1/federation/secret-leases/{lease_id}/revoke — revoke a secret lease

Coordinator: Site Ingest (Pro+)

The inbound surface where sites push their rollups, host directory, command results, metadata, and secret-lease requests up to the coordinator. These endpoints authenticate with the site's long-lived sync token rather than an operator JWT.

  • POST /api/v1/federation/sites/{site_id}/rollups/hosts — ingest host rollup from a site
  • POST /api/v1/federation/sites/{site_id}/rollups/compliance — ingest compliance rollup from a site
  • POST /api/v1/federation/sites/{site_id}/rollups/vulnerabilities — ingest vulnerability rollup from a site
  • POST /api/v1/federation/sites/{site_id}/host-directory — ingest host directory from a site
  • POST /api/v1/federation/sites/{site_id}/command-results — ingest command results from a site
  • POST /api/v1/federation/sites/{site_id}/metadata — ingest site metadata
  • POST /api/v1/federation/sites/{site_id}/secret-lease-requests — ingest secret-lease requests

Site Surface (Pro+)

The site-side surface: enroll with a coordinator, receive policy/command/secret-lease pushes from it, and expose local sync status and the inbound queue to the site operator.

  • POST /api/v1/federation/site/enroll — initiate enrollment with a coordinator
  • GET /api/v1/federation/site/enrollment-status — site enrollment status
  • POST /api/v1/federation/site/policies — receive a policy push from the coordinator
  • POST /api/v1/federation/site/commands — receive a command dispatch from the coordinator
  • POST /api/v1/federation/site/secret-leases — receive a secret lease from the coordinator
  • GET /api/v1/federation/site/sync-status — sync status with the coordinator
  • GET /api/v1/federation/site/sync-queue/depth — depth of the outbound sync queue
  • GET /api/v1/federation/site/received-policies — list policies received from the coordinator
  • GET /api/v1/federation/site/received-commands — list commands received from the coordinator