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.
• 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.

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:

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:

1. From the service account page, click Rotate secret.
2. A new secret is generated; the old secret stops working after a configurable grace window (default: 60 seconds).
3. Update your secrets store with the new value.

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.

Unsupported authentication patterns

• Long-lived static API keys (non-OAuth). OAuth client credentials are the v1 auth model.
• SAML/OIDC SSO integration for service-account provisioning. Service accounts are created in-product.
• Per-call user impersonation (X-On-Behalf-Of). Service accounts act as themselves; there is no impersonation path.
• Token introspection endpoint. The token’s scope and expiry are returned at issuance; there is no separate introspection call.

Next

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