Search directory
Retrieves directory objects that fit the specified search criteria.
GET ~/api/directoryObjects/search?<parameters>
Query parameters
-
Name
-
Required
-
Type
-
Description
-
baseObject
-
False
-
string
-
The identifier of the container, Organizational Unit, or domain to search in. A base object can be identified by:
Distinguished name (DN) {.black}
# Example CN=Users,DC=example,DC=com
Globally unique identifier (GUID) {.black}
# Example 7a4267ce-d354-44e7-8bd6-c681f1284a41
To search everywhere i.e. in all managed domains, don't specify this parameter in the request.
-
oneLevel
-
False
-
bool
-
Set to true to only search across immediate children of the base object. If not specified, Adaxes will seacrh across the entire subtree of the base object. This parameter has no effect if the base object is not specified.
-
filter
-
False
-
string
-
Specify the search criteria as the parameter value. Only the objects that fit the criteria will be retrieved. The following values can be used:
- An LDAP filter e.g. (&(objectCategory=person)(department=Sales)).
- LockedOutAccounts — to retrieve locked user accounts.
- TotpEnrolledAccounts — to retrieve users who activated a mobile authenticator app in Adaxes.
If not specified, all objects located under the base object will be retrieved.
-
properties
-
False
-
string
-
A comma-separated list of LDAP property names without whitespaces e.g. manager,department. Each object in search results will contain the values of specified properties. If not specified, objects will be retrieved with the default property set.
Default property set {.black}
- guid
- dn
- displayName
- objectType
- objectTypeCode
- domainName
-
sizeLimit
-
False
-
integer
-
The maximum number of objects to be retrieved. If not specified, defaults to 1000.
Request headers
-
Name
-
Required
-
Description
-
Adm-Authorization
-
True
-
Specify the security token obtained during authentication.
Request body
Do not send a body with this request.
Responses
- If successful, returns
200 OK
status code and an array of directory objects in the response body. - If successful, and there are no objects to retrieve, returns
200 OK
status code and an empty array in the response body. - If unsuccessful, returns one of the common HTTP error codes and an error description in the response body.
Tip
The response will include only the objects that the authenticated user has the permissions to view. All permissions in Adaxes are granted by security roles.
Examples
Example 1: Find a user with a specific employee ID
The following code sample searches for a user with a specific employee ID in all managed domains.
Request
- PowerShell
-
$ldapFilter = "(employeeId=MyId12345)" $baseUrl = "https://host.example.com/restApi" $endpoint = "/api/directoryObjects/search" $requestUrl = $baseUrl + $endpoint $requestHeaders = @{"Adm-Authorization" = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD"} $requestParams = @{ filter = $ldapFilter; properties = "employeeId" } # Make request Invoke-RestMethod -Method GET -Headers $requestHeaders -Uri $requestUrl -Body $requestParams
- C#
-
using System; using System.Net.Http; using System.Threading.Tasks; class Program { static async Task Main() { const string ldapFilter = "(employeeId=MyId12345)"; const string token = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD"; UriBuilder requestUrl = new UriBuilder( "https://host.example.com/restApi/api/directoryObjects/search"); requestUrl.Query += $"?filter={ldapFilter}"; requestUrl.Query += "&properties=employeeId"; // Initialize HTTP client using (HttpClient client = new HttpClient()) { client.DefaultRequestHeaders.Add("Adm-Authorization", token); // Make request string response = await client.GetStringAsync(requestUrl.ToString()); Console.WriteLine(response); } } }
- cURL
-
curl --header 'Adm-Authorization: HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD' \ --get -X GET 'https://host.example.com/restApi/api/directoryObjects/search' \ --data-urlencode 'filter=(employeeId=MyId12345)' \ --data-urlencode 'properties=employeeId'
- node.js
-
var ldapFilter = encodeURIComponent("(employeeId=MyId12345)"); var https = require("https"); // Request parameters and headers var requestPath = "/restApi/api/directoryObjects/search" + `?filter=${ldapFilter}` + "&properties=employeeId"; var options = { 'method': 'GET', 'hostname': 'host.example.com', 'path': requestPath, 'headers': { "Adm-Authorization": "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD", } }; // Make request var req = https.request(options, function (res) { var chunks = []; res.on("data", function (chunk) { chunks.push(chunk); }); res.on("end", function (chunk) { var body = Buffer.concat(chunks); console.log(body.toString()); }); res.on("error", function (error) { console.error(error); }); }); req.end();
Response
HTTP Status code: 200 OK
Response body:
[
{
"accountStatus": {
"isDisabled": false,
"isLocked": false,
"expirationDate": null
},
"passwordStatus": {
"whenChanged": "2020-09-03T14:18:48.974886Z",
"expirationStatus": 0,
"expirationDate": "2023-05-30T14:18:48.974886Z"
},
"guid": "13ce39d7-183d-41d7-9a6e-ad1ba85b4be3",
"dn": "CN=Nick Johnston,OU=Sales,DC=example,DC=com",
"displayName": "Nick Johnston",
"objectType": "user",
"objectTypeCode": 2,
"domainName": "example.com",
"properties": {
"employeeId": [
"MyId12345"
]
}
}
]
Example 2: Find computers with no owner in a specific OU
The following code sample searches in a specific OU for computers not managed by anyone.
Request
- PowerShell
-
$baseObject = "OU=My Organizational Unit,DC=example,DC=com" $ldapFilter = "(&(objectCategory=computer)(!(managedBy=*)))" $baseUrl = "https://host.example.com/restApi" $endpoint = "/api/directoryObjects/search" $requestUrl = $baseUrl + $endpoint $requestHeaders = @{"Adm-Authorization" = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD"} $requestParams = @{ baseObject = $baseObject; filter = $ldapFilter; oneLevel = $True } # Make request Invoke-RestMethod -Method GET -Headers $requestHeaders -Uri $requestUrl -Body $requestParams
- C#
-
using System; using System.Web; using System.Net.Http; using System.Threading.Tasks; class Program { static async Task Main() { string baseObject = HttpUtility.UrlEncode("OU=My Organizational Unit,DC=example,DC=com"); string ldapFilter = HttpUtility.UrlEncode("(&(objectCategory=computer)(!(managedBy=*)))"); const string token = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD"; UriBuilder requestUrl = new UriBuilder( "https://host.example.com/restApi/api/directoryObjects/search"); requestUrl.Query += $"?baseObject={baseObject}"; requestUrl.Query += $"&filter={ldapFilter}"; requestUrl.Query += "&oneLevel=true"; // Initialize HTTP client using (HttpClient client = new HttpClient()) { client.DefaultRequestHeaders.Add("Adm-Authorization", token); // Make request string response = await client.GetStringAsync(requestUrl.ToString()); Console.WriteLine(response); } } }
- cURL
-
curl --header 'Adm-Authorization: HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD' \ --get -X GET 'https://host.example.com/restApi/api/directoryObjects/search' \ --data-urlencode 'baseObject=OU=My Organizational Unit,DC=example,DC=com' \ --data-urlencode 'filter=(&(objectCategory=computer)(!(managedBy=*)))' \ --data-urlencode 'oneLevel=true'
- node.js
-
var baseObject = encodeURIComponent("OU=My Organizational Unit,DC=example,DC=com"); var ldapFilter = encodeURIComponent("(&(objectCategory=computer)(!(managedBy=*)))"); var https = require("https"); // Request parameters and headers var requestPath = "/restApi/api/directoryObjects/search" + `?baseObject=${baseObject}` + `&filter=${ldapFilter}` + "&oneLevel=true"; var options = { 'method': 'GET', 'hostname': 'host.example.com', 'path': requestPath, 'headers': { "Adm-Authorization": "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD", } }; // Make request var req = https.request(options, function (res) { var chunks = []; res.on("data", function (chunk) { chunks.push(chunk); }); res.on("end", function (chunk) { var body = Buffer.concat(chunks); console.log(body.toString()); }); res.on("error", function (error) { console.error(error); }); }); req.end();
Response
HTTP Status code: 200 OK
Response body:
[
{
"computerType": 1,
"accountStatus": {
"isDisabled": false,
"isLocked": false,
"expirationDate": null
},
"passwordStatus": {
"whenChanged": "2020-10-20T08:14:20.025405Z",
"expirationStatus": 1,
"expirationDate": null
},
"guid": "f722deef-9d4c-4b09-8ec3-4a40cf1a31d8",
"dn": "CN=COMPUTER1,OU=My Organizational Unit,DC=example,DC=com",
"displayName": "COMPUTER1",
"objectType": "computer",
"objectTypeCode": 4,
"domainName": "example.com",
"properties": {}
},
{
"computerType": 0,
"accountStatus": {
"isDisabled": false,
"isLocked": false,
"expirationDate": null
},
"passwordStatus": {
"whenChanged": "2020-11-06T04:03:59.1758971Z",
"expirationStatus": 1,
"expirationDate": null
},
"guid": "9c8163f3-1d97-44b7-867e-2110f8e629db",
"dn": "CN=COMPUTER2,OU=My Organizational Unit,DC=example,DC=com",
"displayName": "COMPUTER2",
"objectType": "computer",
"objectTypeCode": 4,
"domainName": "example.com",
"properties": {}
},
{
"computerType": 1,
"accountStatus": {
"isDisabled": false,
"isLocked": false,
"expirationDate": null
},
"passwordStatus": {
"whenChanged": "2020-10-24T22:49:34.2660542Z",
"expirationStatus": 1,
"expirationDate": null
},
"guid": "8c3848f2-2008-432b-a1a9-942b5dff33ac",
"dn": "CN=COMPUTER3,OU=My Organizational Unit,DC=example,DC=com",
"displayName": "COMPUTER3",
"objectType": "computer",
"objectTypeCode": 4,
"domainName": "example.com",
"properties": {}
}
]
Example 3: Find all security groups with a specific name prefix
The following code sample retrieves all security groups whose name starts with My in all domains.
Request
- PowerShell
-
$ldapFilter = "(&(groupType:1.2.840.113556.1.4.803:=2147483648)(name=My*))" $baseUrl = "https://host.example.com/restApi" $endpoint = "/api/directoryObjects/search" $requestUrl = $baseUrl + $endpoint $requestHeaders = @{"Adm-Authorization" = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD"} $requestParams = @{filter = $ldapFilter} # Make request Invoke-RestMethod -Method GET -Headers $requestHeaders -Uri $requestUrl -Body $requestParams
- C#
-
using System; using System.Web; using System.Net.Http; using System.Threading.Tasks; class Program { static async Task Main() { string ldapFilter = HttpUtility.UrlEncode( "(&(groupType:1.2.840.113556.1.4.803:=2147483648)(name=My*))"); const string token = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD"; UriBuilder requestUrl = new UriBuilder( "https://host.example.com/restApi/api/directoryObjects/search"); requestUrl.Query += $"?filter={ldapFilter}"; // Initialize HTTP client using (HttpClient client = new HttpClient()) { client.DefaultRequestHeaders.Add("Adm-Authorization", token); // Make request string response = await client.GetStringAsync(requestUrl.ToString()); Console.WriteLine(response); } } }
- cURL
-
curl --header 'Adm-Authorization: HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD' \ --get -X GET 'https://host.example.com/restApi/api/directoryObjects/search' \ --data-urlencode 'filter=(&(groupType:1.2.840.113556.1.4.803:=2147483648)(name=My*))'
- node.js
-
var ldapFilter = encodeURIComponent("(&(groupType:1.2.840.113556.1.4.803:=2147483648)(name=My*))"); var https = require("https"); // Request parameters and headers var requestPath = "/restApi/api/directoryObjects/search" + `?filter=${ldapFilter}`; var options = { 'method': 'GET', 'hostname': 'host.example.com', 'path': requestPath, 'headers': { "Adm-Authorization": "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD", } }; // Make request var req = https.request(options, function (res) { var chunks = []; res.on("data", function (chunk) { chunks.push(chunk); }); res.on("end", function (chunk) { var body = Buffer.concat(chunks); console.log(body.toString()); }); res.on("error", function (error) { console.error(error); }); }); req.end();
Response
HTTP Status code: 200 OK
Response body:
[
{
"groupType": 0,
"groupScope": 2,
"membershipType": 0,
"guid": "673017e7-3ce4-4862-9355-969bec56100f",
"dn": "CN=My VPN Group,OU=Groups,DC=example,DC=com",
"displayName": "My VPN Group",
"objectType": "group",
"objectTypeCode": 3,
"domainName": "example.com",
"properties": {}
}
]
Example 4: Retrieve all locked users from a specific domain
The following code sample retrieves all locked user accounts that belong to a specific domain.
Request
- PowerShell
-
$baseObject = "DC=example,DC=com" $criteria = "LockedOutAccounts" $baseUrl = "https://host.example.com/restApi" $endpoint = "/api/directoryObjects/search" $requestUrl = $baseUrl + $endpoint $requestHeaders = @{"Adm-Authorization" = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD"} $requestParams = @{ baseObject = $baseObject; filter = $criteria } # Make request Invoke-RestMethod -Method GET -Headers $requestHeaders -Uri $requestUrl -Body $requestParams
- C#
-
using System; using System.Net.Http; using System.Threading.Tasks; class Program { static async Task Main() { const string baseObject = "DC=example,DC=com"; const string criteria = "LockedOutAccounts"; const string token = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD"; UriBuilder requestUrl = new UriBuilder( "https://host.example.com/restApi/api/directoryObjects/search"); requestUrl.Query += $"?baseObject={baseObject}"; requestUrl.Query += $"&filter={criteria}"; // Initialize HTTP client using (HttpClient client = new HttpClient()) { client.DefaultRequestHeaders.Add("Adm-Authorization", token); // Make request string response = await client.GetStringAsync(requestUrl.ToString()); Console.WriteLine(response); } } }
- cURL
-
curl --header 'Adm-Authorization: HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD' \ --get -X GET 'https://host.example.com/restApi/api/directoryObjects/search' \ --data-urlencode 'baseObject=DC=example,DC=com' \ --data-urlencode 'filter=LockedOutAccounts'
- node.js
-
var baseObject = "DC=example,DC=com"; var criteria = "LockedOutAccounts"; var https = require("https"); // Request parameters and headers var requestPath = "/restApi/api/directoryObjects/search" + `?baseObject=${baseObject}` + `&filter=${criteria}`; var options = { 'method': 'GET', 'hostname': 'host.example.com', 'path': requestPath, 'headers': { "Adm-Authorization": "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD", } }; // Make request var req = https.request(options, function (res) { var chunks = []; res.on("data", function (chunk) { chunks.push(chunk); }); res.on("end", function (chunk) { var body = Buffer.concat(chunks); console.log(body.toString()); }); res.on("error", function (error) { console.error(error); }); }); req.end();
Response
HTTP Status code: 200 OK
Response body:
[
{
"accountStatus": {
"isDisabled": false,
"isLocked": true,
"expirationDate": null
},
"passwordStatus": {
"whenChanged": "2020-10-01T12:26:50.4085035Z",
"expirationStatus": 1,
"expirationDate": null
},
"guid": "2288a376-ef17-4319-8dea-edc291cf892a",
"dn": "CN=John Sally,CN=Users,DC=example,DC=com",
"displayName": "John Sally",
"objectType": "user",
"objectTypeCode": 2,
"domainName": "example.com",
"properties": {}
},
{
"accountStatus": {
"isDisabled": false,
"isLocked": true,
"expirationDate": null
},
"passwordStatus": {
"whenChanged": "2020-10-01T12:26:50.1585044Z",
"expirationStatus": 1,
"expirationDate": null
},
"guid": "4bd4e1ed-be88-457c-ae6e-6aece10fc621",
"dn": "CN=Anna Park,CN=Users,DC=example,DC=com",
"displayName": "Anna Park",
"objectType": "user",
"objectTypeCode": 2,
"domainName": "example.com",
"properties": {}
},
{
"accountStatus": {
"isDisabled": true,
"isLocked": true,
"expirationDate": null
},
"passwordStatus": {
"whenChanged": null,
"expirationStatus": 1,
"expirationDate": null
},
"guid": "7a53db58-87cd-4502-a8b1-d68d5a30bf44",
"dn": "CN=Alfred Junior,CN=Users,DC=example,DC=com",
"displayName": "Alfred Junior",
"objectType": "user",
"objectTypeCode": 2,
"domainName": "example.com",
"properties": {}
}
]
Example 5: Retrieve all users enrolled for MFA in Adaxes
The following code sample retrieves all users who activated a mobile authenticator app in Adaxes.
Request
- PowerShell
-
$criteria = "TotpEnrolledAccounts" $baseUrl = "https://host.example.com/restApi" $endpoint = "/api/directoryObjects/search" $requestUrl = $baseUrl + $endpoint $requestHeaders = @{"Adm-Authorization" = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD"} $requestParams = @{filter = $criteria} # Make request Invoke-RestMethod -Method GET -Headers $requestHeaders -Uri $requestUrl -Body $requestParams
- C#
-
using System; using System.Net.Http; using System.Threading.Tasks; class Program { static async Task Main() { const string criteria = "TotpEnrolledAccounts"; const string token = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD"; UriBuilder requestUrl = new UriBuilder( "https://host.example.com/restApi/api/directoryObjects/search"); requestUrl.Query += $"?filter={criteria}"; // Initialize HTTP client using (HttpClient client = new HttpClient()) { client.DefaultRequestHeaders.Add("Adm-Authorization", token); // Make request string response = await client.GetStringAsync(requestUrl.ToString()); Console.WriteLine(response); } } }
- cURL
-
curl --header 'Adm-Authorization: HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD' \ --get -X GET 'https://host.example.com/restApi/api/directoryObjects/search' \ --data-urlencode 'filter=TotpEnrolledAccounts'
- node.js
-
var criteria = "TotpEnrolledAccounts"; var https = require("https"); // Request parameters and headers var requestPath = "/restApi/api/directoryObjects/search" + `?filter=${criteria}`; var options = { 'method': 'GET', 'hostname': 'host.example.com', 'path': requestPath, 'headers': { "Adm-Authorization": "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD", } }; // Make request var req = https.request(options, function (res) { var chunks = []; res.on("data", function (chunk) { chunks.push(chunk); }); res.on("end", function (chunk) { var body = Buffer.concat(chunks); console.log(body.toString()); }); res.on("error", function (error) { console.error(error); }); }); req.end();
Response
HTTP Status code: 200 OK
Response body:
[
{
"accountStatus": {
"isDisabled": false,
"isLocked": false,
"expirationDate": null
},
"passwordStatus": {
"whenChanged": "2020-10-01T12:26:50.1585044Z",
"expirationStatus": 1,
"expirationDate": null
},
"guid": "4bd4e1ed-be88-457c-ae6e-6aece10fc621",
"dn": "CN=Anna Park,CN=Users,DC=example,DC=com",
"displayName": "Anna Park",
"objectType": "user",
"objectTypeCode": 2,
"domainName": "example.com",
"properties": {}
},
{
"accountStatus": {
"isDisabled": true,
"isLocked": false,
"expirationDate": null
},
"passwordStatus": {
"whenChanged": null,
"expirationStatus": 1,
"expirationDate": null
},
"guid": "7a53db58-87cd-4502-a8b1-d68d5a30bf44",
"dn": "CN=Alfred Junior,CN=Users,DC=example,DC=com",
"displayName": "Alfred Junior",
"objectType": "user",
"objectTypeCode": 2,
"domainName": "example.com",
"properties": {}
}
]
Example 6: Retrieve the emails and mobile numbers of users from a specific department
The following code sample retrieves all users from a specific department and their properties:
- Mobile Phone
Request
- PowerShell
-
$ldapFilter = "(department=Marketing)" $baseUrl = "https://host.example.com/restApi" $endpoint = "/api/directoryObjects/search" $requestUrl = $baseUrl + $endpoint $requestHeaders = @{"Adm-Authorization" = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD"} $requestParams = @{ filter = $ldapFilter; properties = "mail,mobile" } # Make request Invoke-RestMethod -Method GET -Headers $requestHeaders -Uri $requestUrl -Body $requestParams
- C#
-
using System; using System.Net.Http; using System.Threading.Tasks; class Program { static async Task Main() { const string ldapFilter = "(department=Marketing)"; const string token = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD"; UriBuilder requestUrl = new UriBuilder( "https://host.example.com/restApi/api/directoryObjects/search"); requestUrl.Query += $"?filter={ldapFilter}"; requestUrl.Query += "&properties=mail,mobile"; // Initialize HTTP client using (HttpClient client = new HttpClient()) { client.DefaultRequestHeaders.Add("Adm-Authorization", token); // Make request string response = await client.GetStringAsync(requestUrl.ToString()); Console.WriteLine(response); } } }
- cURL
-
curl --header 'Adm-Authorization: HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD' \ --get -X GET 'https://host.example.com/restApi/api/directoryObjects/search' \ --data-urlencode 'filter=(department=Marketing)' \ --data-urlencode 'properties=mail,mobile'
- node.js
-
var ldapFilter = "(department=Marketing)"; var https = require("https"); // Request parameters and headers var requestPath = "/restApi/api/directoryObjects/search" + `?filter=${ldapFilter}` + "&properties=mail,mobile"; var options = { 'method': 'GET', 'hostname': 'host.example.com', 'path': requestPath, 'headers': { "Adm-Authorization": "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD", } }; // Make request var req = https.request(options, function (res) { var chunks = []; res.on("data", function (chunk) { chunks.push(chunk); }); res.on("end", function (chunk) { var body = Buffer.concat(chunks); console.log(body.toString()); }); res.on("error", function (error) { console.error(error); }); }); req.end();
Response
HTTP Status code: 200 OK
Response body:
[
{
"accountStatus": {
"isDisabled": false,
"isLocked": false,
"expirationDate": null
},
"passwordStatus": {
"whenChanged": "2020-10-01T12:26:50.1585044Z",
"expirationStatus": 1,
"expirationDate": null
},
"guid": "4bd4e1ed-be88-457c-ae6e-6aece10fc621",
"dn": "CN=Anna Park,CN=Users,DC=example,DC=com",
"displayName": "Anna Park",
"objectType": "user",
"objectTypeCode": 2,
"domainName": "example.com",
"properties": {
"mail": [ "anna.park@example.com" ],
"mobile": [ "908-432-9108" ]
}
},
{
"accountStatus": {
"isDisabled": true,
"isLocked": false,
"expirationDate": null
},
"passwordStatus": {
"whenChanged": null,
"expirationStatus": 1,
"expirationDate": null
},
"guid": "7a53db58-87cd-4502-a8b1-d68d5a30bf44",
"dn": "CN=Alfred Junior,CN=Users,DC=example,DC=com",
"displayName": "Alfred Junior",
"objectType": "user",
"objectTypeCode": 2,
"domainName": "example.com",
"properties": {
"mail": [ "alfred.junior@example.com" ],
"mobile": [ "405-657-0062" ]
}
}
]