d63af51f84
Some checks failed
api-governance / spectral-lint (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
oas-ci / oas-validate (push) Has been cancelled
SDK Publish & Sign / sdk-publish (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Policy Simulation / policy-simulate (push) Has been cancelled
devportal-offline / build-offline (push) Has been cancelled
51 lines
2.6 KiB
Markdown
51 lines
2.6 KiB
Markdown
# Policy API Reference (runtime endpoints)
|
||
|
||
> **Imposed rule:** Policy API calls must include tenant context and operate on frozen inputs; mutating endpoints require Authority scopes and audit events.
|
||
|
||
## Base
|
||
`/api/v1/policies`
|
||
|
||
## Endpoints
|
||
- `GET /policies` – list policies (with filters: tenant, status, name, tags); paginated.
|
||
- `GET /policies/{id}` – fetch metadata and versions.
|
||
- `GET /policies/{id}/versions/{v}` – fetch IR, hash, status, shadow flag, attestation refs.
|
||
- `POST /policies/{id}/simulate` – run simulate; body: `{ inputs: { sbom_digest, advisory_snapshot, vex_set, reachability_hash, signals_digest }, settings: { shadow: bool } }`. Returns `runId`, findings, explain summary; full explain via run endpoint.
|
||
- `POST /policies/{id}/run` – full run with frozen cursors; same body as simulate plus `mode` (`full|incremental`).
|
||
- `GET /policy-runs/{runId}` – returns findings, explain trace refs, hashes, shadow flag, status.
|
||
- `POST /policies/{id}/submit` – attach lint/simulate/coverage artefacts; transitions to `submitted`.
|
||
- `POST /policies/{id}/approve` – requires `policy:approve`; records approval note.
|
||
- `POST /policies/{id}/publish` – requires `policy:publish`; body includes `reason`, `ticket`, `sign=true|false`; returns attestation ref.
|
||
- `POST /policies/{id}/activate` – requires `policy:activate`; activates version.
|
||
- `POST /policies/{id}/archive` – archive version; reason required.
|
||
|
||
## Headers
|
||
- `X-Stella-Tenant` (required)
|
||
- `X-Stella-Shadow` (optional; simulate)
|
||
- `If-None-Match` (IR cache)
|
||
|
||
## Auth & scopes
|
||
- Read: `policy:read`
|
||
- Simulate: `policy:simulate`
|
||
- Submit: `policy:author`
|
||
- Approve: `policy:approve`
|
||
- Publish/Promote: `policy:publish`/`policy:promote`
|
||
- Activate/Run: `policy:operate`
|
||
|
||
## Errors (Problem+JSON)
|
||
- `policy_inputs_unfrozen` (409) – missing cursors.
|
||
- `policy_ir_hash_mismatch` (409) – IR hash differs from attested value.
|
||
- `policy_shadow_required` (412) – shadow gate not satisfied.
|
||
- `policy_attestation_required` (412) – publish without attestation metadata.
|
||
- Standard auth/tenant errors.
|
||
|
||
## Pagination & determinism
|
||
- `limit`/`cursor`; stable ordering by `policyId` then `version`.
|
||
- All list endpoints return `ETag` and `Content-SHA256` headers.
|
||
|
||
## Offline
|
||
- API supports `file://` bundle handler when running in sealed mode; simulate/run accept `bundle` path instead of remote cursors.
|
||
|
||
## Observability
|
||
- Metrics: `policy_api_requests_total{endpoint,status}`, `policy_simulate_latency_seconds`, `policy_run_latency_seconds`.
|
||
- Logs: include `policyId`, `version`, `runId`, `tenant`, `shadow`, `cursors` hashes.
|