15REST API for integrators

Everything you can do with Active Directory in SYNERGY Management Gateway is also available as a REST API. Integration scripts, identity-management systems, ticketing tools and scheduled jobs can call it directly. The n8n node (Chapter 14, n8n integration) and the MCP server for AI agents (Chapter 13, AI agents (MCP server)) are themselves clients of the same API.

This chapter is for developers and administrators who write such integrations. It covers which part of the API to call, how to authenticate and choose a directory, how responses and errors are shaped, how to handle changes that wait for approval, how to send batches, and the limits the API enforces.

Every request through the API is subject to the same controls as work in the web console: permissions, operation policies, agent supervision, auditing and notifications. The API is not a way around any of them.

The two API surfaces

The gateway serves the same operations under two path prefixes, for two kinds of caller:

Integrations always use /api. It accepts only credentials that a script sends explicitly, never the browser's session cookie. That is what makes it safe to call from a script without the anti-forgery token the console uses. A request to /api that carries only a session cookie is refused.

Do not call /rest from integrations. It exists for the console, expects the console's session and anti-forgery headers, and some of its routes refuse anything other than an interactive browser session.

The base URL

All paths in this chapter are relative to the machine surface root:

https://gateway.example.com/api

If the gateway is installed under an application path in IIS, that path comes first, for example https://gateway.example.com/backend/api. Ask the administrator who installed it. A quick check: GET <base URL>/health answers {"status":"ok", …} when the base URL is right.

The API is served over HTTPS only. Never send an API key over plain HTTP.