Controls

The Controls endpoints expose the organization’s control library: every safeguard your workspace operates, with current implementation and compliance posture.

This is a read-only surface in v1. Creating, updating, and retiring controls happens in the Novantra UI (see the Controls user guide).

For shared conventions (auth, errors, pagination, ID format, reason field), read v1 conventions first.

Scope required

Endpoints

List controls

GET /api/v1/governance/controls
Authorization: Bearer <access-token>

Query parameters:

Response:

{
  "controls": [
    {
      "id": "ctrl_01HXY...",
      "controlKey": "customer-data-encryption-at-rest",
      "title": "Customer data encryption at rest",
      "description": "All customer data stored in primary datastores is encrypted at rest with managed keys.",
      "status": "active",
      "subjectModuleKey": null,
      "subjectResourceType": null,
      "subjectResourceId": null,
      "subjectVersionId": null,
      "ownerResponsibilityAssignmentId": "ra_01HXY...",
      "implementationProjectionId": "geprj_01HXY...",
      "complianceProjectionId": "geprj_01HXZ...",
      "createdAt": "2026-04-15T08:21:43.000Z",
      "updatedAt": "2026-05-25T14:08:33.000Z"
    },
    {
      "id": "ctrl_01HXZ...",
      "controlKey": "vendor-onboarding-due-diligence",
      "title": "Vendor onboarding due diligence",
      "description": "Every new third-party vendor passes due-diligence review before contract signing.",
      "status": "active",
      "subjectModuleKey": null,
      "subjectResourceType": null,
      "subjectResourceId": null,
      "subjectVersionId": null,
      "ownerResponsibilityAssignmentId": "ra_01HXZ...",
      "implementationProjectionId": "geprj_01HXY...",
      "complianceProjectionId": "geprj_01HXY...",
      "createdAt": "2026-04-15T08:25:11.000Z",
      "updatedAt": "2026-04-15T08:25:11.000Z"
    }
  ],
  "pagination": {}
}

Get one control

GET /api/v1/governance/controls/:controlId
Authorization: Bearer <access-token>

Path parameters:

Response:

{
  "control": {
    "id": "ctrl_01HXY...",
    "controlKey": "customer-data-encryption-at-rest",
    "title": "Customer data encryption at rest",
    "description": "All customer data stored in primary datastores is encrypted at rest with managed keys.",
    "status": "active",
    "subjectModuleKey": null,
    "subjectResourceType": null,
    "subjectResourceId": null,
    "subjectVersionId": null,
    "ownerResponsibilityAssignmentId": "ra_01HXY...",
    "implementationProjectionId": "geprj_01HXY...",
    "complianceProjectionId": "geprj_01HXZ...",
    "createdAt": "2026-04-15T08:21:43.000Z",
    "updatedAt": "2026-05-25T14:08:33.000Z"
  }
}

Field notes

implementationProjectionId and complianceProjectionId

Each control carries two separate projection references:

• implementationProjectionId points at the current implementation projection (a record in the evaluation-projections layer) that summarizes whether the control is in place.
• complianceProjectionId points at the current compliance projection that summarizes whether the control is currently producing the intended outcome.

In v1 these are returned as opaque IDs. The projection records themselves are not represented by separate v1 endpoints; the values they resolve to (e.g., implemented, compliant) live in the in-product UI.

subjectModuleKey, subjectResourceType, subjectResourceId, subjectVersionId

When a control applies to a specific governed object (a particular asset, a particular service), these fields identify it. For organization-wide controls (the common case), all four are null. See Attaching records to governed subjects.

ownerResponsibilityAssignmentId

Points at the responsibility assignment naming the accountable owner. The responsibility-assignment record itself is not a v1 endpoint; the in-product UI shows the owner name and role.

Real-case integration: pulling the control register into a SIEM context

A platform engineering team runs a SIEM that correlates security telemetry with the organization’s control posture. When the SIEM alerts on an unusual event, the analyst wants to know which controls were supposed to prevent or detect this category of event, who owns those controls, and whether they were reported as compliant at the time the event occurred.

The team’s integration pulls the control register nightly:

1. Calls GET /api/v1/governance/controls?status=active and stores each row.
2. The SIEM-side enrichment maps event categories (failed auth, data exfiltration attempt, unexpected admin action) to control keys it knows about.
3. When an alert fires, the analyst dashboard surfaces the matching controls with their current owner and compliance projection ID, plus a link back to the Novantra workspace for the full record.

The integration’s service account holds exactly governance.controls:read. It walks with cursor pagination and respects rate-limit headers. Daily refresh is sufficient because controls change rarely; the per-event lookups against the cached register are fast and don’t hit the API.

For lower-latency operational dashboards, combine daily pull with webhook events from the resources that drive control posture changes. Daily pull is the supported pattern for the control register itself.

Related

• Controls user guide - what the controls module does and when to reach for it.
• v1 conventions - shared request and response patterns.
• Authentication - service accounts and scopes.