Authentication

The v1 API authenticates with scoped bearer tokens issued to service accounts. Human user sessions and personal user tokens are not accepted on /api/v1/....

Why service accounts

A service account is a non-human identity in your workspace that owns API credentials. Compared to using a human user’s session:

It survives the human leaving the organization.
It can be scoped narrowly (e.g., read-only access to findings) rather than carrying the human’s full role.
It acts as itself, so its activity is attributed to a clear, named integration in the audit log.
It supports clean rotation: rotate the service account’s credentials without touching anyone’s login.

Every integration should use its own service account. Do not share one service account across multiple integrations.

Getting a service account

Workspace admins create service accounts from Developers -> API -> Credentials in the Novantra web app. For each service account you set:

A descriptive name (“ServiceNow Findings Sync”, “Splunk Audit Export”).
A scope set describing what this integration is allowed to do (see Scopes below).
An optional expiry date.

When you save, the system issues a client ID and client secret. The client secret is shown once at creation time. Capture it and store it in your integration’s secrets store.

The client secret cannot be retrieved later. If lost, rotate it (which issues a new secret and invalidates the old one).

Credential posture

The Developers API surface shows safe credential posture for each service account:

storage posture, such as digest-only;
reveal posture, such as one-time create or rotate;
last rotation time;
next rotation due date, when configured;
last verification time, when available;
whether customer action is required.

This posture is evidence for your integration operations. It is not a way to retrieve a client secret, bearer token, secret digest, or provider credential. If a service account shows customer action required, update your own secrets store or rotate/disable the credential according to your security process.

Novantra evaluates this posture from safe rotation metadata. Depending on your configured rotation policy, a credential can move from current to due soon, overdue, or customer-action-required without exposing the secret value.

Getting an access token

The v1 API uses OAuth 2.0 client credentials. Exchange your client ID and secret for a short-lived access token:


POST /api/v1/auth/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "svc_01EXAMPLE00000000000000000",
  "client_secret": "<client-secret>"
}

Response:


{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "governance.controls:read governance.findings:write"
}

Cache the token until just before it expires; do not request a new one for every call.

Use the token in subsequent requests:


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

Scopes

Tokens carry scopes describing what the integration is allowed to do. Scopes use the format <resource>:<action>, for example governance.controls:read or governance.findings:write.

A non-exhaustive scope catalogue:

Scope	Permits
`governance.controls:read`	List and get controls.
`governance.risks:read`	List and get risks.
`governance.evidence:read`	List and get evidence requirements and claims.
`governance.evidence:write`	Create evidence claims (with attachments).
`governance.assessments:read`	List and get assessments.
`governance.findings:read`	List and get findings.
`governance.findings:write`	Create and update findings.
`governance.exceptions:read`	List and get exceptions.
`governance.monitoring:read`	List monitor definitions and runs.
`governance.indicators:read`	List and get indicators and measurements.
`governance.submissions:read`	List submission requirements and packages.
`governance.submissions:write`	Record submission package events.
`governance.frameworks:read`	List frameworks and versions.
`assets:read`	List and get assets.
`party-engagements:read`	List and get party engagements.
`change-management:read`	List and get change requests, baselines, releases.
`vulnerability-management:read`	List and get vulnerabilities and assessments.
`webhooks:manage`	Create, update, and delete webhook subscriptions for this service account.

Scopes follow the least privilege principle. A service account that only ingests findings from a scanner needs governance.findings:write and nothing else. Do not request broader scopes than your integration uses.

Rotation

Rotate the client secret periodically (your security policy decides how often; quarterly is a reasonable baseline). Rotation:

From the service account page, click Rotate secret.
A new secret is generated; the old secret stops working after the rotation completes.
Update your secrets store with the new value.
Review the credential posture so the service account no longer shows stale or customer-action-required evidence.

Rotating does not invalidate active access tokens that were already issued against the old secret. Those expire on their normal expires_in and are renewed against the new secret.

Revocation

If a credential is compromised:

Rotate the secret immediately to invalidate it.
Disable the service account to invalidate all active tokens regardless of which secret issued them.

A disabled service account refuses to issue new tokens and any in-flight tokens fail with 401 on the next call.

Versioning - how the v1 contract evolves.
Governance reference - per-resource endpoints.