How to use NIM APIs

Products Identity Manager Show & Tell
, , , , ,
1

Introduction

Netwrix Identity Manager (NIM) exposes a complete REST API enabling third-party systems to interact programmatically with the solution. This API is the foundation of advanced integrations: feeding identities from an external portal, triggering workflows, querying the role model, or launching synchronization jobs.

This document is a practical guide intended for presales teams, consultants, and integrators. It covers the entire NIM API usage cycle: activation, authentication, read calls, triggering actions, and best practices.

Typical use cases

  • Create or modify an identity from an HR portal or an external ITSM
  • Query a user’s permissions in real time
  • Automatically trigger an access request workflow
  • Launch a synchronization job from an orchestrator (Ansible, Azure DevOps…)
  • Export audit data to a SIEM or a dashboard
  • Integrate NIM into a Zero Trust architecture for continuous access validation

Key principle:
Any action that can be performed from the NIM web interface can also be performed via the REST API. The API and the UI share the same engine and the same permission rules.

NIM API Architecture

Two exposure points

NIM exposes its APIs from two distinct components:

Component Role Example endpoints
NIM Server Data, role model, workflows, governance /api/Resource, /api/Job, /api/Workflow
NIM Agent Local actions on the client IT system (provisioning, jobs) /api/Job/Launch, /api/Agent/Status

In a SaaS architecture, the server is hosted by Netwrix and the agent is installed on the client’s network. Traffic is always initiated from the agent to the server (outbound only). The server API is accessible from outside; the agent API is only accessible from the internal network.

Swagger Interface

The interactive API documentation is available via Swagger. It lets you browse all endpoints, test calls live, and download the OpenAPI definition in JSON format.

  • Swagger URL: [your NIM instance URL]/swagger
  • OpenAPI definition (JSON): [URL]/swagger/{version}/swagger.json
  • Anonymous access to the page, but each call requires authentication

Activation required
The Swagger interface is disabled by default. It must be explicitly enabled in the ‘Swagger settings’ section of the NIM server’s network configuration. Do not expose it in production without appropriate access control.

Authentication

OpenID Connect Protocol

The NIM API is secured by the OpenID Connect (OIDC) protocol. Each client application must be registered as an OpenIdClient in the NIM XML configuration, with an identifier (clientId) and a hashed secret.

The NIM server’s OIDC configuration is accessible at:

GET [URL NIM]/.well-known/openid-configuration

Declaring an OpenIdClient

In the NIM XML configuration (configuration file), declare a client as follows:

<OpenIdClient     
  Identifier="MyApplication"      
  HashedSecret="[secret hash]"      
  DisplayName_L1="API Client - External Application "     
  Profile="Administrator" />   

<!-- For a profile restricted to a specific scope: -->
<OpenIdClient
  Identifier="HRApp"
  HashedSecret="[secret hash]"
  DisplayName_L1="HR Connector"
  Profile="HROperator" />
  • The plaintext secret is never stored in NIM, only its SHA256 hash
  • Generate the hash with the utility: Usercube-New-OpenIDSecret.exe
  • Each clientId must have a dedicated profile (principle of least privilege)

Obtaining an access token

The client_id to use in OIDC calls is the concatenation of the application’s identifier and domain:
client_id = "MyApplication@mycompany.usercube. com "

Call to the token endpoint (client_credentials flow): 

POST [URL NIM]/connect/token
Content-Type: application/x-www-form-urlencoded 
grant_type=client_credentials
&client_id=MyApplication@mycompany.usercube.com
&client_secret=MySercretClearText
&scope=usercube_api

Response (JSON):

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Then use this token in the Authorization header of each API call:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Via Swagger
If you are already logged in to the NIM application in the same browser, authentication in Swagger is automatic via the session cookie. Ideal for interac t i ve testin g.

Query language — squery

NIM has a proprietary query language (squery) used in the query parameter of GET calls. It lets you express precisely the data you want: column selection, filters, joins, sorting, pagination.

Refer to the official documentation for more details: API query grammar | Netwrix Product Documentation

Postman Configuration: Step-by-step Demo

Postman is the recommended tool for testing and documenting NIM API calls. Here is the complete procedure for setting up an operational Postman environment.

Create a Postman Environment

  • Open Postman > Environments > New Environment
  • Name the environment: “NIM - [Client name]”
  • Create the following variables:
Variable Example value Description
nim_url https://mycompany.usercube.com Base URL of the NIM instance
client_id MyApplication@mycompany.usercube.com Full OIDC client_id
client_secret (plaintext secret) Secret generated with New-OpenIDSecret
access_token (auto-filled) JWT token obtained after auth

Obtain the token (Pre-request Script)

In a Postman collection, add a Pre-request Script at the collection level to automatically obtain and store the token:

const tokenUrl = pm.environment.get('nim_url') + '/connect/token';
const clientId = pm.environment.get('client_id');
const clientSecret = pm.environment.get('client_secret');

pm.sendRequest({
  url: tokenUrl,
  method: 'POST',
  header: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: {
    mode: 'urlencoded',
    urlencoded: [
      { key: 'grant_type', value: 'client_credentials' },
      { key: 'client_id', value: clientId },
      { key: 'client_secret', value: clientSecret },
      { key: 'scope', value: 'usercube_api' }
    ]
  }
}, (err, res) => {
  pm.environment.set('access_token', res.json().access_token);
});

Configure Authorization

  • In the collection settings: Authorization > Bearer Token
  • Token: {{access_token}}
  • All calls in the collection will automatically use this token

Test a first call

GET {{nim_url}}/api/Resource/Directory_User?squery=select Id,FirstName,LastName,Email pagesize 5

Headers:
  Authorization: Bearer {{access_token}}
  Accept: application/json

Error handling

HTTP Code Meaning Corrective action
400 Bad Request Invalid parameters or missing data Check the request body and required fields
401 Unauthorized Token missing or expired Renew the token via /connect/token
403 Forbidden Insufficient permissions Check the profile permissions associated with the OpenIdClient
404 Not Found Resource not found Check the resource identifier
429 Too Many Requests Rate limit reached Implement an exponential backoff

Useful Resources and Links

Resource URL / Reference
Official API documentation API | Netwrix Product Documentation
squery syntax API query grammar | Netwrix Product Documentation
Postman how-to Request Usercube's API via Postman | Netwrix Product Documentation
OpenIdClient XML config docs.netwrix.com/docs/identitymanager/saas/integration-guide/toolkit/xml-configuration/access-control/openidclient/
Security certifications trust.netwrix.com
3 Likes