5.10Managing connections through the REST API

Last updated 9 October 2026

Connections can also be managed through the REST API, with an API key or bearer token that carries the permissions listed in 5.1. The endpoints are listed below relative to the machine surface /api; Chapter 15, REST API for integrators, explains authentication and the two API surfaces.

Method and path	Permission	Purpose
`GET /api/ad/connections?pageNumber=1&pageSize=50`	`adconnections:list`	List connections, with health (at most 100 per page)
`GET /api/ad/connections/{id}`	`adconnections:read`	Read one connection
`POST /api/ad/connections`	`adconnections:create`	Create a connection
`PUT /api/ad/connections/{id}`	`adconnections:update`	Change settings
`POST /api/ad/connections/{id}/reset-password`	`adconnections:update`	Rotate the stored bind password
`POST /api/ad/connections/{id}/test`	`adconnections:read`	Test and record health
`DELETE /api/ad/connections/{id}`	`adconnections:delete` + System Admin	Delete a connection
`GET /api/ad/connections/{id}/protected-ous`	`adconnections:read`	List protected containers
`POST /api/ad/connections/{id}/protected-ous`	`adconnections:update`	Protect a container
`DELETE /api/ad/connections/{id}/protected-ous/{rowId}`	`adconnections:update`	Remove a protection
`GET /api/ad/connections/selectable`	`ad:directory:read`	Connections the caller's role may use
`GET /api/settings/directory-client`	`adconnections:read`	Read the directory client settings in force (see 5.12)
`PUT /api/settings/directory-client`	`adconnections:update`	Save the directory client settings

The password is never returned by any of these endpoints.

The directory client settings take and return maxRetryAttempts, initialRetryDelayMs, enableConnectionHealthCheck and schemaWarmupClasses; a save must name all four (an empty schemaWarmupClasses list warms nothing). The read also returns source (configuration or saved), updatedAt and updatedBy.

Note: An API key can never delete a connection, whatever permissions its role holds, because an API key never acts with the System Admin role. Delete connections from the console, signed in with System Admin as your active role.

An example request to create a connection:

http

POST /api/ad/connections
X-API-Key: <your key>
Content-Type: application/json

{
  "controller": "dc1.corp.local",
  "domain": "corp.local",
  "username": "svc-gateway@corp.local",
  "password": "<bind password>",
  "useSsl": true,
  "port": 636,
  "baseDn": "OU=Corp,DC=corp,DC=local",
  "description": "Production domain, HQ",
  "tags": ["production"]
}

A successful create answers 201 Created with the new connection, including its id. Rotating the password takes a body of the form { "newPassword": "<new password>" }. Protecting a container takes { "distinguishedName": "OU=Tier0,DC=corp,DC=local", "note": "Tier 0" }.

A test answers with the reading it recorded:

json

{
  "connectionId": "8f6c1a52-3a8e-4c34-9a4f-6a0d2b1e7c10",
  "isConnected": true,
  "message": "Successfully connected to Active Directory",
  "testedAt": "2026-10-03T09:14:22Z"
}

The message text is whatever the domain controller and the platform report, and differs between successes and the various failures. In the list response, each connection's health field is one of Healthy, Unreachable or Unknown, with healthMessage and healthCheckedAt beside it.

Good practice

Use a dedicated service account per installation, with rights delegated on the organizational units the platform should manage. Avoid Domain Admin.
Prefer LDAPS, and make sure the platform's server trusts the domain controller's certificate.
Rotate the bind password regularly. The list highlights passwords never rotated or older than a year. Change the password in Active Directory first, then select Change password on the connection.
Subscribe someone to Directory Credentials Rejected so a broken service-account password is noticed before users report it.
Tag your connections so production and test directories cannot be confused in the workspace picker.
Protect your most sensitive containers before you connect AI agents or issue API keys for a directory.
Bind roles to specific directories rather than Every directory where your organisation separates administration by domain.
Select Save current values on the Directory client screen once (see 5.12, Before the first save), so its settings are kept in the database and survive a re-run of the setup wizard.

Last updated 9 October 2026