Policies API v1

Applies to: Nirmata Control Hub 4.0 and later

The Policies API v1 is a JSON REST API for the policy and compliance data in Nirmata Control Hub. Use it to read policy reports and findings, manage policy exceptions and exception requests, and work with compliance standards, controls, and compliance reports.

Unlike the model-based platform API, the v1 API uses fixed resource paths and plain JSON request and response bodies. The URL parameters (fields, filter, query, and so on) and common endpoints do not apply to v1 endpoints.

Base URL

All endpoints are served under:

https://<your-nirmata-host>/policies/api/v1

For Nirmata Control Hub SaaS, <your-nirmata-host> is nirmata.io.

Authentication

Every request needs an Authorization header. Two schemes are supported:

Authorization: NIRMATA-API <api-token>
Authorization: Bearer <jwt>

To create an API token, see API Tokens. Requests run as the user who owns the token, scoped to that user’s tenant. You never pass a tenant ID explicitly.

export NIRMATA_URL=https://nirmata.io
export NIRMATA_TOKEN=<api-token>

curl -s -H "Authorization: NIRMATA-API $NIRMATA_TOKEN" \
  "$NIRMATA_URL/policies/api/v1/policy-reports?limit=10"

Roles

Access is controlled by the user roles in Nirmata Control Hub (see Users and Roles). Each endpoint lists the roles allowed to call it. The table below summarizes the default permissions for the resources in this reference:

An endpoint’s role list can be narrower than this table. For example, approving an exception request may be limited to specific roles. A request from a user whose role is not allowed returns 403 Forbidden.

Pagination

List endpoints accept limit and offset query parameters and return a page envelope:

{
  "items": [ ... ],
  "total": 132,
  "limit": 50,
  "offset": 0
}

Some endpoints use a different envelope or extra filter parameters. Each endpoint’s reference documents its own response shape.

Errors

Errors return a standard HTTP status code and a JSON body with an error message:

{ "error": "Policy exception not found" }

Endpoint groups