15.3Base paths
Last updated
The table lists the main areas of the machine API. Each area holds several endpoints; the OpenAPI document (see "OpenAPI and Swagger" below) lists every route with its parameters.
| Base path | What it covers |
|---|---|
/ad/users | Users: search, read, create, update, delete, enable, disable, unlock, password reset and change, account expiry, group membership, move, rename, SPNs, batch |
/ad/groups | Groups: search, read, create, update, delete, members, move, rename, batch |
/ad/computers | Computer accounts: search, read, create, update, delete, enable, disable, unlock, password reset, account expiry, linked service accounts, move, rename, SPNs |
/ad/organization-units | Organizational units: search, read, create, update, delete, move, rename, protection from deletion, bulk enable or disable of the accounts inside, batch |
/ad/objects | Any directory object by GUID: search, look-up by distinguished name, read, create, update, move, rename, delete, access control lists, delegations, batch |
/ad/accounts/search, /ad/computers/accounts/search | User and computer accounts by state: locked out, disabled, expired, inactive and others |
/ad/service-accounts | Managed and group managed service accounts |
/ad/deleted-objects | Deleted objects (Recycle Bin): list, check, restore. Needs the Recycle Bin module on the licence. |
/ad/domain, /ad/forest, /ad/root-dse, /ad/directory-context | Domain, forest and RootDSE information |
/ad/domain-controllers, /ad/sites, /ad/subnets, /ad/site-links, /ad/trusts | Replication topology and trusts |
/ad/optional-features, /ad/kds-root-keys | Optional features and KDS root keys |
/ad/domain/password-policy, /ad/fine-grained-password-policies | The domain password policy and fine-grained password policies |
/ad/delegation-templates | Named delegation templates |
/ad/{users,groups,computers,organization-units,objects}/schema | The attributes each object type accepts |
/saved-ldap-filters | Shared saved LDAP filters, and running them |
/operations | Your own queued operations; with the matching permissions, the operations log and operation policies |
/health | Liveness check, no credential needed |
/metadata | Version information; needs any valid credential |
The installation's own administration (platform users, roles, API keys, notifications, single sign-on, licence, updates) is also reachable on /api for automation, with the corresponding permissions, but most integrations need only the /ad, /saved-ldap-filters and /operations areas.
Common Active Directory routes
| Method and path | What it does | Permission |
|---|---|---|
GET /ad/users?baseDn=… | Search users under a container | ad:users:read |
GET /ad/users/{id} | Read one user | ad:users:read |
POST /ad/users | Create a user | ad:users:create |
PATCH /ad/users/{id} | Update a user | ad:users:update |
DELETE /ad/users/{id} | Delete a user | ad:users:delete |
POST /ad/users/{id}/enable, /disable, /unlock | Change account state | ad:users:update |
POST /ad/users/{id}/reset-password | Set a new password | ad:users:update |
POST /ad/users/{id}/groups | Add the user to a group | ad:groups:update |
GET /ad/groups/{id}/members | List members | ad:groups:read |
POST /ad/groups/{id}/members | Add a member | ad:groups:update |
PATCH /ad/objects/{id}/move | Move an object | ad:objects:update |
PATCH /ad/users/{id}/move | Move a user, refusing any object that is not a user | ad:users:update |
GET /ad/objects/{id}/acl | Read an access control list | ad:acl:read |
GET /saved-ldap-filters/{id}/results | Run a saved filter | savedfilters:execute |
GET /operations/{id} | Poll one of your own operations | operations:waiting:list |
Move and rename exist both on /ad/objects/{id} and on the typed areas (/ad/users, /ad/groups, /ad/computers, /ad/organization-units). The typed routes check that the GUID belongs to an object of that type and answer 404 otherwise, so a wrong ID cannot move the wrong object; prefer them when you know the type. A rename changes the object's name in the directory tree only, not its logon name.
Objects are addressed by their objectGUID in the path. Every {id} must be a GUID; any other value does not match a route and returns 404.
Two endpoint families exist only on the machine surface: the twelve batch endpoints (described below) and the single sign-on callbacks used by identity providers.
Last updated
Thank you for your feedback.