Operator - Security

Overview

Security APIs summarize policy violations, service-agent role coverage, installed policy packs, and SOC 2 or GDPR report freshness. They also provide the governed write paths for resolving findings, assigning agent security roles, and generating reports.

Human roles and agent roles are separate

Workspace membership controls who can use this API. A service agent's admin, operator, or agent security_role contributes to gateway permission evaluation but never grants a human operator session.

Reports are point-in-time snapshots

The overview marks compliance attention when critical violations are open or the latest SOC 2/GDPR snapshot is missing or older than 30 days. Generating a report persists the selected window; it does not continuously update.

How it works

1. Read posture before remediating

   Start with /security, then filter open violations by severity, type, service agent, or connector. Inspect the linked audit event and effective agent permissions before changing a role or policy.

2. Resolve with evidence

   Remediate the cause, verify new behavior, then resolve the violation. Generate a SOC 2 or GDPR report for a valid window of at most 365 days and retain its generated_at timestamp.

Examples

These examples are illustrative. Replace the sample values with your own. Keep credentials in environment variables or a secret manager, never in client-side code.

const response = await fetch("/api/v1/operator/security", {
  credentials: "same-origin",
  headers: {"Accept": "application/json"}
});
const body = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${body.detail}`);
console.log(body);

Troubleshooting

An active member gets 403 on GET

Security applies a stricter domain rule than general operator reads: only owner, admin, and auditor memberships may view posture. An active member-role membership still receives 403.

Report generation returns 422

Use framework soc2 or gdpr, ensure period_start precedes period_end, and keep the inclusive reporting window at 365 days or less.

Endpoint reference

Ready to integrate? Open an endpoint for its required permissions, request fields, response format, and status codes. The examples above explain the workflow; these details define each individual request.