Exceptions API

Exceptions are time-bound, tenant-scoped, auditable objects that change policy outcomes in StellaOps without mutating upstream evidence. Use them for waivers, compensating controls, and scoped suppressions in a way that is fully replayable offline.

Audience: integrators and operators automating exception governance. This document is the entry point for exception contracts; the concrete request/response shapes live in the gateway and Console schemas listed under API Surfaces.

Core Concepts

• Exception object: { exceptionId, tenantId, scope, vuln, effect, justification, owner, expiration, evidenceRefs, policyBinding, status }
• Append-only history: changes are recorded as transitions; revoke/expire supersedes instead of delete.
• Two-phase activation (recommended): draft → staged → active to support simulation and controlled rollout.
• Effects: examples include suppress, defer, downgrade, requireControl (exact effect catalog is policy-driven).

API Surfaces

• Console CRUD/workflow (gateway-proxied): see docs/api/console/exception-schema.md
• Policy + Exceptions gateway contract: docs/api/gateway/policy-exceptions.md
• Exception workflow events (SSE stream): docs/api/gateway/exception-events.md

Security & Headers

Common requirements across endpoints:

• Authorization: Bearer <token> (or DPoP where configured)
• Tenant header (required): prefer X-StellaOps-TenantId (legacy aliases: X-StellaOps-Tenant, X-Stella-Tenant); see docs/api/gateway/tenant-auth.md.

Scopes vary by deployment, but typically follow:

• Read: exceptions:read
• Create/edit: exceptions:write
• Approve/reject/revoke: exceptions:approve
• Simulation endpoints: policy:simulate (plus exceptions:read when simulating with overrides)

Offline / Air-Gap

• Imports/exports are file-based (NDJSON or JSON) with deterministic ordering and UTC timestamps.
• Signed exports (DSSE) are supported when Attestor is enabled; when disabled, exports remain hash-addressed and reproducible.

Related Docs

• Exception Governance migration guide: docs/technical/migration/exception-governance.md
• CLI usage guide: docs/modules/cli/guides/exceptions.md