Manage the Nodinite Web API

Everything you do in the Nodinite Web Client goes through the Web API. Your own scripts, services, and DevOps pipelines can call the same REST operations: add or update Integrations in the Repository Model as part of a release, read monitoring state for an intranet page, or change run-time behavior from your own apps.

This page is the starting point for programmatic access. It explains how authentication works, how to find the operations you need, which System Parameters the Web API reads and changes, and when to use the Web API instead of the AI-driven MCP Endpoint. The step-by-step guides with code are in the Scenarios.

• ✅ Automate documentation and configuration as part of your DevOps and CI/CD pipelines
• ✅ Call REST operations from PowerShell, curl, C#, Python, Node.js, or any HTTP client
• ✅ Authenticate with Windows Authentication or OAuth 2.0 client credentials
• ✅ Get deterministic results: the same request returns the same data, every time

Note

Nodinite does not issue its own API keys. Depending on the authentication mode of your environment, a script either uses a Windows identity or sends an OAuth 2.0 access token from your identity provider as a bearer token.

Understanding Programmatic Access

Your code calls the Web API (blue) directly with a Windows identity, or first gets a token from the identity provider (purple) in OAuth 2.0 mode. Nodinite Roles (green) limit what each caller can see and do, and changes are recorded in Log Audits.

Key Components

Choose Your Authentication Method

Your environment's authentication mode decides the method. Follow the matching scenario:

Warning

In OAuth 2.0 mode, don't reuse the installation client (NodiniteInstallationClient) for your own scripts. It has full access. Register one client per calling system and give it a least-privilege Role, as described in the OAuth 2.0 guide.

For OAuth configuration of the environment itself, see Install Nodinite v7 - OpenID. The Web API Audiences value, which your client's token must be issued for, is set in the Portal in the Auth step, Web API section. In Windows Authentication mode, the Web API's service identity is set in the Auth step, Service Account Defaults, or per service in the Servers step.

Web API or MCP Endpoint?

Nodinite offers two ways for software to work with your environment. They solve different problems:

Tip

Use both: explore with an AI tool through the MCP Endpoint to find out what to automate, then put the repeatable steps in a script that calls the Web API. Inside the Web Client, the AI Assistant answers questions without any setup on your side. For the big picture, read AI in Nodinite.

Where to go next, depending on what you want to do with the MCP Endpoint:

• Connect VS Code or another MCP client: Set up the MCP Endpoint (Getting Started, Track 3).
• Reach the MCP Endpoint from outside the server with OAuth 2.0: MCP Endpoint External Access.
• See which tools an AI client can call: MCP Tool Reference.
• Plan hosting, ports, install, and update of the endpoint: MCP Endpoint (Core Services).
• Ask about BizTalk Server applications: BizTalk and MCP Endpoint.

Find the Base URL

In Nodinite v7, each environment's Web API is its own IIS web site with its own port, and the operations are served from the root of that site. The base URL is the scheme, host, and port, for example https://nodinite.contoso.com:40001. The port is set for each environment in the Nodinite Portal, under Core platform services in the Servers step, so yours probably differs from the examples. The host name (FQDN) and the TLS certificate are set in the same step, under Core host Configuration. The examples use <webapi-base-url> for this address.

Important

This is the Nodinite v7 URL format: one web site and port per environment, with the operations at the root of the site. Always call the Web API over HTTPS in production. The Log API has its own web site and base URL.

Tip

To check that you have the right base URL, add /scalar or /swagger to it and open it in your browser. If the API reference opens, the base URL is correct.

Find Operations in Scalar or Swagger

The Web API comes with two interactive API references. Both list every operation with its parameters and request and response models, and both let you send test requests as the signed-in user before you script the call.

Tip

Prefer Scalar for new work. Nodinite v7 ships with both, but Swagger may be removed in a future version of the Web API. Scalar's code snippets don't include authentication: add the Authorization header or Windows credentials as shown in the Scenarios.

Scalar groups the operations by area, generates a code snippet for the selected language, and shows the response models for each status code.

In Swagger, Try it out and Execute send the request and show the curl command, the request URL, and the response body.

Most operations return their data under Collection.Items[].Data, as the whoami response above shows. For example, the first Integration Id from api/integrations is Collection.Items[0].Data.IntegrationId.

Code Samples by Language

Any language with an HTTP client works the same way. Scalar also generates a starting snippet for each operation in many languages; add authentication as shown in the scenarios. For Java, request a token as in the curl example and send it in the Authorization header.

What You Can Automate

• Documentation as part of DevOps: create or update Integrations and other Repository Model artifacts from your build and release pipeline, so the documentation never falls behind.
• Run-time changes: change settings and behavior from your own apps and scripts.
• Data for other systems: read data for your intranet, wiki, custom portals, and reports.

Important

Store client secrets and passwords in a secret store such as Azure Key Vault, HashiCorp Vault, or your pipeline's secret variables. Never commit secrets to source control, and never log tokens.

System Parameters

System Parameters are environment-wide settings stored in the SystemParameters table of the Configuration Database. The Web API reads some of them, and it hosts the operations that change them, both for the Web Client and for your own scripts. How to change a value in the Web Client, the data types, and how fast a change takes effect are explained once, in Manage System Parameters. No System Parameter needs a restart of the Web API: v7 caches each value for about 15 seconds.

Parameters the Web API Reads

Change System Parameters Through the Web API

Deployment and automation scripts can change values with the same operations the Web Client uses. Find them in Scalar at <webapi-base-url>/scalar, and authenticate as described in Choose Your Authentication Method.

Warning

The PUT operation doesn't validate the value. Call ValidateJson first before you script a change to a json parameter. The full walkthrough is in Change a Value Through the Web API.

MaintenanceMode Is a Web API Flag

Set MaintenanceMode with PUT api/SystemParameters/MaintenanceMode. With true, the Web API stops loading plugins and reports maintenance status. It does not pause the Logging Service or the Monitoring Service, and it doesn't suppress alerts. To pause the services, use Stop Services on the Log Databases page; to warn users about planned maintenance, use a User Notification.

Next Steps

• Call the Web API with OAuth 2.0 Client Credentials
• Call the Web API with Windows Authentication
• Web API Scenarios
• Manage System Parameters
• Set up the MCP Endpoint

Related Topics

• Web API
• MCP Endpoint
• MCP Endpoint External Access
• MCP Tool Reference
• MCP Endpoint (Core Services)
• AI in Nodinite
• System Parameters
• Configuration Database
• Log API
• Install Nodinite v7
• Install Nodinite v7 - OpenID
• Register Nodinite Applications in Azure AD (Entra ID) with OpenID
• Web API Troubleshooting