Governance reference
This section is the per-resource v1 endpoint reference. Each page below documents the endpoints, scopes, request and response shapes, and a real-case integration example for one resource.
Before drilling into a specific resource, make sure you’ve read:
- v1 conventions for the shared request and response patterns.
- Authentication for service accounts and scopes.
- Errors for the error envelope and idempotency.
What’s in v1
v1 is read-heavy. The integrations Novantra wants to support out of the gate are:
- Pull governance data into a warehouse or BI tool.
- Push findings into Novantra from external scanners.
- Push evidence into Novantra from external systems (backup logs, configuration snapshots, SBOM exports).
- Record submission package status callbacks from regulator portals.
| Resource | Read | Write |
|---|---|---|
| Frameworks | yes | not in v1 |
| Controls | yes | not in v1 |
| Risks | yes | not in v1 |
| Evidence | yes | create claim with attachments |
| Assessments | yes | not in v1 |
| Findings | yes | create, update status |
| Exceptions | yes | not in v1 |
| Monitoring | runs only | not in v1 |
| Indicators | yes | not in v1 |
| Submissions | yes | record package events |
| Assets | yes | not in v1 |
| Party Engagements | yes | not in v1 |
| Change Management | yes | not in v1 |
| Vulnerability Management | yes | not in v1 |
What’s not in v1
The governance foundation includes additional modules that ship in the product but are not part of the v1 API surface:
- Scope, Management Systems, Evaluation Models, Applicability - foundation configuration that workspace admins manage in the UI.
- Assurance, Access governance, Retention - oversight modules with sensitive workflow semantics. Mutations are admin-only and stay in the product UI for v1.
- Secure Development, Network & Communications, Security Operations, Cryptography, Facilities Security, Cloud Governance - operational domains that stay outside the public v1 contract.
For these modules, see the corresponding user guide for what they do; if your integration needs programmatic access, raise it with your account team.
Adding a module to v1 is a deliberate decision. Each public resource needs scopes, write semantics, rate limits, webhook coverage, and OpenAPI integration before it belongs in the external contract. Do not assume everything in the user guides is available through v1.
Scopes summary
Read scopes use the pattern <resource-module>:read. Write scopes use <resource-module>:write. The full catalogue lives on the Authentication page.
The least-privileged token an integration can hold is one with exactly the scopes it uses. A read-only warehouse loader needs governance.controls:read governance.risks:read (and similar) and nothing else.
Webhook coverage
Resources with corresponding webhook events:
- Findings (
finding.created,finding.updated,finding.closed) - Evidence claims (
evidence.claim.created,.approved,.rejected) - Submissions (
submission.package.status_changed,submission.package.event_recorded) - Assessments (
assessment.completed)
See Webhooks for the full event catalogue, payload shape, signature verification, and delivery semantics.