Phase 8 Foundation Features API

List every access group (flat). Each row carries parent_id; tree assembly is the client's job. Returns 200 with an array of {id, name, description, parent_id, created_at, updated_at}.

Create a new group. Body: {name, description?, parent_id?}. Returns 200 on success, 404 if parent_id doesn't exist, 400 on cycle / depth violation. Tree depth is capped at 10.

Read one group.

Update name / description / parent. Cycle detection re-runs against the new parent.

Delete. Children are reparented to the deleted group's parent (or to root) per the FK ON DELETE SET NULL rule.

List every registration key without secrets. The plaintext key is only ever returned at create time.

Create. Body: {name, access_group_id?, auto_approve?, max_uses?, expires_at?}. Response includes the plaintext key field exactly once — it is never recoverable.

Mark revoked. Idempotent. Existing host enrollments are not affected.

Delete the key row. (Use revoke instead if you want to keep the audit trail.)

List profiles with their next-run timestamps.

Create. Body: {name, description?, cron, enabled?, security_only?, package_managers?, staggered_window_min?, tag_id?}. cron validates against the OSS POSIX cron parser (lists, ranges, step intervals, day/month names, dom/dow OR-semantics). staggered_window_min is clamped to [0, 720] minutes.

Read one.

Update. Cron changes recompute next_run automatically.

Delete.

Fire a profile NOW. Resolves the target host set, enqueues an apply_updates command per host (with the profile's flags + staggered-window delay), updates last_run / next_run, and returns the dispatched host list.

Driver hook for an external scheduler. Selects every enabled profile where next_run <= now, fires it, and returns the fired list. Idempotent within a tick.

List profiles (without constraints).

Create. Body: {name, description?, enabled?, constraints[]} where each constraint is {package_name, package_manager?, constraint_type, version_op?, version?}. constraint_type is REQUIRED or BLOCKED; version_op is one of =, ==, >=, <=, >, <, !=, ~=.

Read with constraints.

Update. Constraint list is replaced atomically — pass the full desired list.

Delete.

Evaluate the host's cached software_package inventory against the profile, persist the result in HostPackageComplianceStatus, and return it. Fast but only as fresh as the most recent inventory upload.

Ask the agent to evaluate compliance against its live local package state and report back via the WS command-result channel. Slower round-trip but always-current.

Latest compliance status for one host across all profiles. Each row contains {status, violations[], last_scan_at}.

Body: {broadcast_action, message?, parameters?, tag_id?, platform?}. Returns {broadcast_id, broadcast_action, delivered_count, elapsed_ms, target_filter}. SLA: under 5 s for fleets up to 100 hosts.

Common actions: refresh_inventory (re-collect software inventory), banner + message (display a notification on the agent host).

Read current branding. Logo bytes are not included; has_logo indicates whether one is configured.

Update company_name and header_text. Empty strings clear the field.

Upload (or replace) the org logo. multipart/form-data with a file field. Allowed: PNG, JPEG, SVG, WEBP. Max size 1 MB.

Stream the logo bytes. Used by the frontend preview AND embedded as a data URL by the reporting engine.

Remove the configured logo (text fields untouched).

List templates.

Create. Body: {name, description?, base_report_type, selected_fields[], enabled?}. selected_fields entries must be valid codes for the chosen base_report_type; unknown codes are rejected with 400.

Read one.

Update.

Delete.

List the eight base report types (registered-hosts, hosts-with-tags, users-list, firewall-status, antivirus-opensource, antivirus-commercial, user-rbac, audit-log) that templates can be built on.

Catalog of available {code, label} pairs for the base type. The frontend uses this to populate the field-picker UI.

Issue a new lease. Body: {name, kind, backend_role, ttl_seconds, note?}. kind is token, database, or ssh; ttl_seconds is clamped to [60, 86400]. Response: {lease, secret} — surface secret to the operator once and discard.

List leases. Optional filters: ?status=ACTIVE|REVOKED|EXPIRED|FAILED, ?kind=token|database|ssh.

Read one lease (no secret).

Revoke immediately and delete from OpenBAO. Idempotent.

Sweeper hook — transitions ACTIVE rows whose expires_at has passed into EXPIRED. Safe to call repeatedly.

Catalog of supported lease kinds and the TTL range.