REST API overview
Netwrix Privilege Secure has a REST API. Every operation that the console performs goes through this API, so a script or an external tool can do the same work that an administrator does in the console.
The API returns JSON and uses standard HTTP methods. This page describes the conventions that apply to every endpoint. To get a token, see Authenticate to the API.
Base URL
The API listens on the same server and port as the console.
https://<nps-server>:6500/api/v1/
Each resource group is a controller name appended to the base URL, for example https://<nps-server>:6500/api/v1/ActivitySession. A few sign-in endpoints sit at the root of the site instead, such as https://<nps-server>:6500/signinBody. See Authenticate to the API.
Use port 6500, the default console port, for API calls.
Two endpoints report on the server itself:
| Endpoint | Returns |
|---|---|
GET /api/v1/health | The health of the web service. |
GET /api/v1/Version | The product version. |
Authentication
Every request, except the sign-in requests, carries a bearer token in the Authorization header.
Authorization: Bearer <token>
A token is valid for 15 minutes by default. The token lifetime is a server setting, separate from the console's UI Idle Timeout. A script that runs longer renews the token before it expires. Two kinds of account can request a token:
| Account | Use it for | Credentials |
|---|---|---|
| User | Interactive scripts that run as a person. | User name and password, plus a second factor if the user's authentication connector requires one. |
| Application user | Unattended automation. | Client certificate serial number and API key. |
For the steps, see Authenticate to the API. To create an application user, see Add application users.
Roles and permissions
The role of the account that owns the token decides what each endpoint allows. A user token carries the roles of that user. An application user token is built the same way: it carries the roles that the application user has through console access and the roles assigned to it. An application user without a role can't call endpoints that require one. Give an application user only the roles that its tool needs, and give the API key and client certificate only to tools that you trust with those roles. For the roles that exist in the console, see Roles and permissions. To assign roles, see Assign administrators, reviewers, and auditors.
Searching and paging
List endpoints are named Search and page their results with query parameters.
| Parameter | Description |
|---|---|
skip | The number of records to skip. |
take | The number of records to return. |
filterText | Text to match. Many endpoints add their own filters, for example a date range or a credential type. |
The following request returns the first 30 records of the activity session search.
GET https://<nps-server>:6500/api/v1/ActivitySession/Search?skip=0&take=30&filterText=
The response holds the records in a data property and the total number of matching records in recordsTotal. Some endpoints add properties to this envelope. The activity session search adds topUsers and summary. To read all records, repeat the request and raise skip by the take value until a page returns fewer records than take.
The default value of take differs between endpoints, for example 10 for activity sessions and 100 for users and groups. Some endpoints cap take. The search for group and role candidates accepts at most 1000.
Resource groups
The API groups its endpoints by the areas of the console.
| Area | Examples of what you can do |
|---|---|
| Authentication and sessions | Sign in, renew a token, sign out. |
| Users, groups, and roles | Create users and application users, assign roles. |
| Resources and discovery | Manage resources, resource groups, platforms, and host scans. |
| Credentials and rotation | Search credentials, view passwords, and rotate passwords. |
| Access policies and activities | Manage policies, activities, approval workflows, and command restrictions. |
| Session recording and audit | Read activity sessions and replay data, run reports. |
| Integrations and notifications | Manage integration connectors, SIEM servers and templates, and email. |
| Platform administration | Read and change system settings, license information, and configuration export and import. |
Errors
The API reports most errors as an HTTP status code with a JSON body in the standard problem details format. Some sign-in failures return a plain text message instead, for example "Invalid Username or Password". The message for a failed application user sign-in is intentionally vague.
Swagger
The API can publish a Swagger page that lists its endpoints. Swagger is off by default.
To turn it on, add "SwaggerEnable": true to C:\ProgramData\Stealthbits\PAM\WebService\appsettings.json, and restart the web application. The server reads the setting at startup. If the file doesn't exist, create it with this setting inside a JSON object.
When Swagger is off, the /swagger addresses don't return an error. The server answers with the console page, status 200 and content type text/html, so a request for /swagger/v1/swagger.json returns HTML and not a specification.
Calling the API from a script
Use PowerShell 7 or curl. If the server certificate isn't trusted for the address you use, for example when you connect to localhost and the certificate names the server, Windows PowerShell 5.1 reports "The underlying connection was closed: Could not establish trust relationship for the SSL/TLS secure channel." Connect with the host name in the certificate. The server answers a request that addresses it as localhost with HTTP 400.
Trust the certificate authority (CA) that issued the server certificate instead of turning certificate checks off. With curl, point the client at the CA certificate file with --cacert <ca-certificate-file>.
The SbPAMPowershellModules.msi installer in the Extras folder installs the SbPAMAPI PowerShell module, which wraps these calls with cmdlets such as Get-SbPAMToken and Invoke-SbPAMRest. The Knowledge Base articles that use it call for PowerShell 7. This guide doesn't document the full cmdlet list.