Nuronus API Documentation

Overview

The Nuronus API exposes each client organization's live security and compliance data over HTTPS with JSON responses. Nuronus owns the connections to each client's environment (Microsoft 365, Google Workspace, RMM tools, cloud platforms) — your integration reads the assessed results; it never needs credentials for the underlying environments.

Base URL: https://nuronus.com/api/v1

Authentication

Every request must include an API key in the X-API-Key header:

curl https://nuronus.com/api/v1/clients \
  -H "X-API-Key: nuronus_a1b2c3d4_..."

API keys are issued by your Nuronus account administrator and look like nuronus_<prefix>_<secret>. Each key carries an explicit set of scopes (for example read:clients, read:compliance) and can be restricted to specific client organizations and source IP addresses. Keys are stored hashed on our side and shown only once at creation — store yours in a secrets manager or environment variable, never in source control. Keys can be rotated at any time without changing anything else about the integration.

• Missing or invalid key → 401 Unauthorized
• Key lacks the required scope → 403 Forbidden
• Key not authorized for the requested client → 403 Forbidden

Rate limits

Default limits are 60 requests per minute, 1,000 per hour, and 10,000 per day per key (your administrator can adjust these per key). Responses include standard RateLimit-* headers; exceeding a limit returns 429 Too Many Requests. Back off and retry after the window resets.

Response format

Successful responses wrap the result in a data field. List endpoints add a pagination object and accept ?limit= (max 100) and ?offset=. Errors return an appropriate HTTP status with this body:

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "API key missing required scope: read:compliance"
  }
}

Clients

Client organizations are the unit of tenancy. Call the list endpoint once, store the Nuronus client id (UUID) against your own records, and pass it in the path of every other request.

Required scope: read:clients

Lists all active clients visible to the key. Optional query filter: industry.

{
  "data": [
    {
      "id": "0f7c2a4e-9c1b-4e2a-8f3d-1a2b3c4d5e6f",
      "name": "Acme Medical Group",
      "industry": "healthcare",
      "employeeCount": 45,
      "createdAt": "2026-03-02T18:11:04.000Z"
    }
  ],
  "pagination": { "total": 12, "limit": 50, "offset": 0 }
}

Required scope: read:clients

Returns one client's details, including settings and timestamps.

Assets

Required scope: read:assets

Lists a client's discovered and managed assets. Optional filters: category, assetType, isCritical=true. Each asset includes status, criticality, owner, risk score, and discovery timestamps.

Required scope: write:assets

Creates an asset in Nuronus (useful for pushing inventory from an external system). externalId is your identifier and is required. Valid assetType values: user, device, server, workstation, mobile, network_device, virtual_machine, container, saas_app, cloud_resource, identity, mailbox, file_share, database.

{
  "clientId": "0f7c2a4e-9c1b-4e2a-8f3d-1a2b3c4d5e6f",
  "name": "FILESRV01",
  "externalId": "your-system-id-123",
  "assetType": "server",
  "category": "infrastructure",
  "isCritical": true,
  "owner": "[email protected]",
  "tags": ["production", "file-server"]
}

Required scope: write:assets

Updates an existing asset. All fields optional: name, displayName, category, isCritical, owner, description, tags.

Security scores

Required scope: read:scores

Returns the current security score with a letter grade (A ≥ 90, B ≥ 80, C ≥ 70, D ≥ 60, F below) plus score history. Optional ?limit= controls how many historical entries are returned (default 30, max 100).

{
  "data": {
    "current": {
      "overallScore": 74,
      "grade": "C",
      "categoryScores": { "identity": 68, "endpoint": 81 },
      "controlsTotal": 45,
      "controlsCompliant": 27,
      "controlsPartial": 9,
      "controlsNonCompliant": 9,
      "calculatedAt": "2026-07-15T06:00:12.000Z"
    },
    "history": []
  }
}

Risks

Required scope: read:risks

Returns risk items from the client's latest risk assessment, ordered by risk score. Optional filter: severity (critical, high, medium, low). Each item includes title, description, category, severity, estimated dollar impact, and risk score.

Compliance

Required scope: read:compliance

High-level rollup: readiness score and control pass/partial/fail counts per framework. Use this for dashboards and summary views.

{
  "data": [
    {
      "framework": "CIS_V8",
      "totalControls": 45,
      "passedControls": 27,
      "partialControls": 9,
      "failedControls": 9,
      "readinessScore": 70
    }
  ]
}

Required scope: read:compliance

Requirement-keyed detail for one framework. Each entry is keyed by the framework's own control reference — SOC 2 CC6.1, HIPAA 164.312(a)(1), CMMC AC.L2-3.1.1— so results join directly against your own control tables. Each requirement carries an overall status, a 0–100 compliance score, and the mapped technical control results (status, score, findings, remediation guidance, and assessment timestamp) as supporting detail.

{
  "data": {
    "frameworkId": "SOC2",
    "frameworkName": "SOC 2 Type II",
    "frameworkVersion": "2017",
    "requirements": [
      {
        "requirement": "CC6.1",
        "description": "Logical access security software, infrastructure,
          and architectures over protected information assets",
        "overallStatus": "partial",
        "complianceScore": 62,
        "controls": [
          {
            "controlCode": "CIS-6.3",
            "title": "Require MFA for Externally-Exposed Applications",
            "status": "non_compliant",
            "score": 40,
            "findings": "12 of 45 users have no MFA method registered.",
            "remediation": "Enable a Conditional Access policy requiring
              MFA for all users on all cloud apps.",
            "assessedAt": "2026-07-15T06:00:12.000Z"
          }
        ]
      }
    ]
  }
}

Framework IDs

An unknown framework ID returns 404 with the supported list in the error message.

Status values

For a binary met / not-met interpretation, treat compliant as met and everything else as not met (handle partial per your own policy).

Webhooks

Instead of (or alongside) polling, Nuronus can push events to your endpoint. Your Nuronus administrator registers the webhook URL and selects the events to subscribe to. Every delivery is an HTTPS POST with a JSON body:

{
  "id": "evt_9f8e7d6c5b4a",
  "type": "compliance_status_changed",
  "created": "2026-07-15T06:01:44.000Z",
  "data": {
    "mspId": "...",
    "clientId": "0f7c2a4e-9c1b-4e2a-8f3d-1a2b3c4d5e6f",
    "object": { "framework": "SOC2", "readinessScore": 62 },
    "previous": { "readinessScore": 71 }
  }
}

Delivery headers

• X-Nuronus-Signature — HMAC-SHA256 hex digest of the raw request body, computed with your webhook's signing secret
• X-Nuronus-Event-Id — unique per event; use it for idempotency (retries reuse the same ID)
• X-Nuronus-Event-Type — the event name
• X-Nuronus-Delivery-Attempt — attempt number; failed deliveries are retried with exponential backoff

Verifying signatures

Always verify the signature against the raw request body before parsing (the same pattern as Stripe webhooks). Respond with a 2xx status quickly; do heavy processing asynchronously.

const crypto = require('crypto');

function verifyNuronusSignature(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

Event types

Recommended pattern: treat webhooks as triggers and the API as the source of truth. On compliance_status_changed or integration_sync_completed, re-pull the compliance endpoints for that client rather than relying on the event payload as complete state.

Getting access

API keys and webhook subscriptions are managed by the Nuronus account administrator (the MSP, MSSP, or vCISO running your compliance program). If you are integrating on behalf of one of their clients, ask them for a key scoped to the clients and permissions you need. If you are evaluating Nuronus itself, book a demo or start a free account.