Get directory object

Retrieves a directory object.

GET ~/api/directoryObjects?<parameters>

Query parameters

Name
Required
Type
Description
directoryObject
True
string

The identifier of the directory object to retrieve. You can use:

Distinguished name (DN)

# Example
CN=John Smith,CN=Users,DC=example,DC=com

Globally unique identifier (GUID)

# Example
7a4267ce-d354-44e7-8bd6-c681f1284a41

Security identifier (SID)

# Example
S-1-5-21-3635565734-1729062999-1822655016-1627

properties
False
string
A comma-separated list of property names without whitespaces e.g. manager,department to retrieve. If not specified, the object will be retrieved with the default property set.
Default property set
- guid
- dn
- displayName
- objectType
- objectTypeCode
- domainName
- directoryType

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 a directory object in the response body. Otherwise, returns one of the common HTTP error codes and an error description in the response body.

Examples

Example 1 – Retrieve a user

The following code sample retrieves a user object using only the mandatory request parameters.

Request

PowerShell

$baseUrl = "https://host.example.com/restApi"
$endpoint = "/api/directoryObjects"

# Request parameters
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = YOUR-SECURITY-TOKEN}
$queryParams = @{"directoryObject" = "CN=John Smith,CN=Users,DC=example,DC=com"}

# Make request
Invoke-RestMethod -Method GET -Headers $requestHeaders -Uri $requestUrl -Body $queryParams

C#

using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        const string baseUrl = "https://host.example.com";
        const string endpoint = "/restApi/api/directoryObjects";

        // Request parameters
        const string userIdentifier = "CN=John Smith,CN=Users,DC=example,DC=com";
        UriBuilder requestUrl = new()
        {
            Host = baseUrl + endpoint,
            Query = $"?directoryObject={userIdentifier}"
        };

        // Initialize HTTP client
        using HttpClient client = new();
        client.DefaultRequestHeaders.Add("Adm-Authorization", YOUR-SECURITY-TOKEN);

        // Make request
        string response = await client.GetStringAsync(requestUrl.ToString());
        Console.WriteLine(response);
    }
}

cURL

curl  --header 'Adm-Authorization: YOUR-SECURITY-TOKEN' \
--get -X GET 'https://host.example.com/restApi/api/directoryObjects' \
--data-urlencode 'directoryobject=CN=John Smith,CN=Users,DC=example,DC=com'

node.js

var https = require('https');

// Request parameters
var userIdentifier = "CN=John Smith,CN=Users,DC=example,DC=com";
var requestPath = "/restApi/api/directoryObjects"
    + `?directoryobject=${userIdentifier}`;

var options = {
    'method': 'GET',
    'hostname': 'host.example.com',
    'path': encodeURI(requestPath),
    'headers': {'Adm-Authorization': 'YOUR-SECURITY-TOKEN'}
};

// Make request
var req = https.request(options, res => {
    var data = [];

    res.on("data", chunk => {
        data.push(chunk);
    });

    res.on("end", () => {
        var body = Buffer.concat(data);
        console.log(body.toString());
    });

    res.on("error", error => {
        console.error(error);
    });
});
req.end();

Python

import requests
import json

baseUrl = "https://host.example.com/restApi"
endpoint = "/api/directoryObjects"

# Request parameters
requestUrl = baseUrl + endpoint
requestHeaders = {"Adm-Authorization": YOUR-SECURITY-TOKEN}
queryParams = {"directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com"}

# Make request
request = requests.get(requestUrl, headers=requestHeaders, params=queryParams)
response = json.loads(request.content)
print(response)

Response

HTTP Status code: 200 OK
Response body:

{
    "accountStatus": {
        "isDisabled": false,
        "isLocked": false,
        "expirationDate": null
    },
    "passwordStatus": {
        "whenChanged": "2020-07-14T16:27:49.5590448Z",
        "expirationStatus": 0,
        "expirationDate": "2020-08-09T16:27:49.5590448Z"
    },
    "guid": "7a4267ce-d354-44e7-8bd6-c681f1284a41",
    "dn": "CN=John Smith,CN=Users,DC=example,DC=com",
    "displayName": "John Smith",
    "objectType": "user",
    "objectTypeCode": 2,
    "domainName": "example.com",
    "directoryType": 1,
    "properties": {}
}

Example 2 – Retrieve a user with photo and department

The following code sample retrieves a user object with their photo and department. The photo is returned as a Base64-encoded string.

Request

PowerShell

$baseUrl = "https://host.example.com/restApi"
$endpoint = "/api/directoryObjects"

# Request parameters 
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = YOUR-SECURITY-TOKEN}
$queryParams = @{
    "directoryObject" = "CN=John Smith,CN=Users,DC=example,DC=com";
    "properties" = "department,thumbnailPhoto"
}

# Make request
Invoke-RestMethod -Method GET -Headers $requestHeaders -Uri $requestUrl -Body $queryParams

C#

using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        const string baseUrl = "https://host.example.com";
        const string endpoint = "/restApi/api/directoryObjects";

        // Request parameters
        const string userIdentifier = "CN=John Smith,CN=Users,DC=example,DC=com";
        const string propertiesToGet = "department,thumbnailPhoto";
        UriBuilder requestUrl = new()
        {
            Host = baseUrl + endpoint,
            Query = $"?directoryObject={userIdentifier}" + $"&properties={propertiesToGet}"
        };

        // Initialize HTTP client
        using HttpClient client = new();
        client.DefaultRequestHeaders.Add("Adm-Authorization", YOUR-SECURITY-TOKEN);

        // Make request
        string response = await client.GetStringAsync(requestUrl.ToString());
        Console.WriteLine(response);
    }
}

cURL

curl  --header 'Adm-Authorization: YOUR-SECURITY-TOKEN' \
--get -X GET 'https://host.example.com/restApi/api/directoryObjects' \
--data-urlencode 'directoryobject=CN=John Smith,CN=Users,DC=example,DC=com' \
--data-urlencode 'properties=department,thumbnailphoto'

node.js

var https = require('https');

// Request parameters
var userIdentifier = encodeURIComponent("CN=John Smith,CN=Users,DC=example,DC=com");
var propertiesToGet = "department,thumbnailPhoto";
var requestPath = "/restApi/api/directoryObjects"
    + `?directoryobject=${userIdentifier}`
    + `&properties=${propertiesToGet}`;

var options = {
    'method': 'GET',
    'hostname': 'host.example.com',
    'path': requestPath,
    'headers': {'Adm-Authorization': 'YOUR-SECURITY-TOKEN'}
};

// Make request
var req = https.request(options, res => {
    var data = [];

    res.on("data", chunk => {
        data.push(chunk);
    });

    res.on("end", () => {
        var body = Buffer.concat(data);
        console.log(body.toString());
    });

    res.on("error", error => {
        console.error(error);
    });
});
req.end();

Python

import requests
import json

baseUrl = "https://host.example.com/restApi"
endpoint = "/api/directoryObjects"

# Request parameters
requestUrl = baseUrl + endpoint
requestHeaders = {"Adm-Authorization": YOUR-SECURITY-TOKEN}
queryParams = {
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "properties": "department,thumbnailPhoto"
}

# Make request
request = requests.get(requestUrl, headers=requestHeaders, params=queryParams)
response = json.loads(request.content)
print(response)

Response

HTTP Status code: 200 OK
Response body:

{
    "accountStatus": {
        "isDisabled": false,
        "isLocked": false,
        "expirationDate": null
    },
    "passwordStatus": {
        "whenChanged": "2020-07-14T16:27:49.5590448Z",
        "expirationStatus": 0,
        "expirationDate": "2020-08-09T16:27:49.5590448Z"
    },
    "guid": "7a4267ce-d354-44e7-8bd6-c681f1284a41",
    "dn": "CN=John Smith,CN=Users,DC=example,DC=com",
    "displayName": "John Smith",
    "objectType": "user",
    "objectTypeCode": 2,
    "domainName": "example.com",
    "directoryType": 1,
    "properties": {
        "department": [ "Marketing" ],
        "thumbnailPhoto": [
        "iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAAA
        XNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsM
        AAA7DAcdvqGQAAAvWSURBVHhe7ZsJcJXVFceZdgadqVaZqRapI
        lVQKKBF1GppFcSNVrGtS4vUWu1icRw7tbZ1WGRH9q2swbBHVhF
        BUUCWkD0h+x5CCFlJQhKyhyycnt9978IzhDxe+nAgvP/Mm/e9m
        +99797/Pefe8z/nptOZM2de19fKq/XVSUQ26+uqBRaw0nl9VcJ
        HgI8AHwHtJyCtuEYSCqul+nSTs8U98irqZUVkgdQ1Njtb3KOmo
        Vn89DuFVaedLd5DuwgIya6QAQui5Iczw+X26WHyfECS8y/uEZ5
        TKYP9YuVUXaOzxT1O6MB/vjxWEk9Um8+QAZHegMcEHDlZK9eND
        5J3Pss0HSuvbZT4wiqp1VnK1L81NJ8x9+VqB0uqG8z1sbI6M4t
        HS+vMfTmn6qXpjOM+EFtQZf7miiL9bmRuhZTWOIjiO6ebzkjY8
        QrpPDZQrShf0ktqJUufbVGllkj/PIHHBLy984jcv+iw89M5JBf
        VyPenhkh2uaNDv1idIGP3ZAnj7D03Qh77ME6eWZMon6WelF6zw
        01nGfTDS2LkJ0ui5a7ZEfLO55nmu2tjTshA/Y2haikLQ/OkXt3
        lDrW2sJwKeeOTdLl2XKD8eGGUTD1wXO6YFS5JTst4a8cRGbkpx
        VxfLDwm4HH/OP2hDOenc0hSAr43OfgsAU+vipfRu7PMdZdJQfL
        +3mNm9oOOnZIffBBqLOJZJeS3HyULtpChM/cdtaxwHeRTK+Nlm
        L6sjRSrNdwyLVSi8iqlvqlZblW3wxLAo0rS5P3Z5rrP3Ej5KrP
        MXF8sPCbg95tS5bEVcc5P54AFdJ0WIgWVDt8cvjZRxqgFNKsJ0
        OHD2nkQrh2/fUaYFFY2mNn7PO2kaQcDdFaXRxRIhpr2kOUxMlD
        XmS8zSqVGrcU+wxKAe4B1sSfkCf94CdXnPqBWw+95Ao8JOKQz2........",
        ]
    }
}

Example 3 – Retrieve a user with Adaxes custom attributes

The following code sample retrieves a user object with the values of the following Adaxes custom attributes:

Custom boolean attribute (adm-CustomAttributeBoolean1)
Custom date attribute (adm-CustomAttributeDate1)
Custom DN syntax attribute (adm-CustomAttributeObject1)

Adaxes custom attributes are retrieved just like any other attributes.

Request

PowerShell

$baseUrl = "https://host.example.com/restApi"
$endpoint = "/api/directoryObjects" 

# Request parameters
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = YOUR-SECURITY-TOKEN}
$queryParams = @{
    "directoryObject" = "CN=John Smith,CN=Users,DC=example,DC=com";
    "properties" = 
        "adm-CustomAttributeBoolean1,adm-CustomAttributeDate1,adm-CustomAttributeObject1"
}

# Make request
Invoke-RestMethod -Method GET -Headers $requestHeaders -Uri $requestUrl -Body $queryParams

C#

using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        const string baseUrl = "https://host.example.com";
        const string endpoint = "/restApi/api/directoryObjects";

        // Request parameters
        const string userIdentifier = "CN=John Smith,CN=Users,DC=example,DC=com";
        const string propertiesToGet = 
            "adm-CustomAttributeBoolean1,adm-CustomAttributeDate1,adm-CustomAttributeObject1";
        UriBuilder requestUrl = new()
        {
            Host = baseUrl + endpoint,
            Query = $"?directoryObject={userIdentifier}" + $"&properties={propertiesToGet}"
        };

        // Initialize HTTP client
        using HttpClient client = new();
        client.DefaultRequestHeaders.Add("Adm-Authorization", YOUR-SECURITY-TOKEN);

        // Make request
        string response = await client.GetStringAsync(requestUrl.ToString());
        Console.WriteLine(response);
    }
}

cURL

curl  --header 'Adm-Authorization: YOUR-SECURITY-TOKEN' \
--get -X GET 'https://host.example.com/restApi/api/directoryObjects' \
--data-urlencode 'directoryobject=CN=John Smith,CN=Users,DC=example,DC=com' \
--data-urlencode 'properties=adm-CustomAttributeBoolean1,adm-CustomAttributeDate1,adm-CustomAttributeObject1'

node.js

var https = require('https');

// Request parameters
var userIdentifier = encodeURIComponent("CN=John Smith,CN=Users,DC=example,DC=com");
var propertiesToGet = 
    "adm-CustomAttributeBoolean1,adm-CustomAttributeDate1,adm-CustomAttributeObject1";
var requestPath = "/restApi/api/directoryObjects"
    + `?directoryobject=${userIdentifier}`
    + `&properties=${propertiesToGet}`;

var options = {
    'method': 'GET',
    'hostname': 'host.example.com',
    'path': requestPath,
    'headers': {'Adm-Authorization': 'YOUR-SECURITY-TOKEN'}
};

// Make request
var req = https.request(options, res => {
    var data = [];

    res.on("data", chunk => {
        data.push(chunk);
    });

    res.on("end", () => {
        var body = Buffer.concat(data);
        console.log(body.toString());
    });

    res.on("error", error => {
        console.error(error);
    });
});
req.end();

Python

import requests
import json

baseUrl = "https://host.example.com/restApi"
endpoint = "/api/directoryObjects"

# Request parameters
requestUrl = baseUrl + endpoint
requestHeaders = {"Adm-Authorization": YOUR-SECURITY-TOKEN}
queryParams = {
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "properties": "adm-CustomAttributeBoolean1,adm-CustomAttributeDate1,adm-CustomAttributeObject1"
}

# Make request
request = requests.get(requestUrl, headers=requestHeaders, params=queryParams)
response = json.loads(request.content)
print(response)

Response

HTTP Status code: 200 OK
Response body:

{
    "accountStatus": {
        "isDisabled": false,
        "isLocked": false,
        "expirationDate": null
    },
    "passwordStatus": {
        "whenChanged": null,
        "expirationStatus": 2,
        "expirationDate": null
    },
    "guid": "1d6fcc50-ab32-4419-bf67-9ac6b5dfc3be",
    "dn": "CN=John Doe,CN=Users,DC=example,DC=com",
    "displayName": "John Doe",
    "objectType": "user",
    "objectTypeCode": 2,
    "domainName": "example.com",
    "directoryType": 1,
    "properties": {
        "adm-CustomAttributeBoolean1": [ true ],
        "adm-CustomAttributeDate1": [ "2021-11-27T10:00:00Z" ],
        "adm-CustomAttributeObject1": [ "CN=My Group,OU=Groups,DC=example,DC=com" ]
    }
}

Example 4 – Retrieve a group, its owners, and its members

The following code sample retrieves a group object and the distinguished names (DNs) of all its owners and members using the optional properties parameter in the request.

Request

PowerShell

$baseUrl = "https://host.example.com/restApi"
$endpoint = "/api/directoryObjects"  

# Request parameters
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = YOUR-SECURITY-TOKEN}
$queryParams = @{
    "directoryObject" = "CN=My Group,OU=Groups,DC=example,DC=com";
    "properties" = "member,adm-Owners"
}
 
# Make request
Invoke-RestMethod -Method GET -Headers $requestHeaders -Uri $requestUrl -Body $queryParams

C#

using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        const string baseUrl = "https://host.example.com";
        const string endpoint = "/restApi/api/directoryObjects";

        // Request parameters
        const string groupIdentifier = "CN=My Group,OU=Groups,DC=example,DC=com";
        const string propertiesToGet = "member,adm-Owners";
        UriBuilder requestUrl = new()
        {
            Host = baseUrl + endpoint,
            Query = $"?directoryObject={groupIdentifier}" + $"&properties={propertiesToGet}"
        };

        // Initialize HTTP client
        using HttpClient client = new();
        client.DefaultRequestHeaders.Add("Adm-Authorization", YOUR-SECURITY-TOKEN);

        // Make request
        string response = await client.GetStringAsync(requestUrl.ToString());
        Console.WriteLine(response);
    }
}

cURL

curl  --header 'Adm-Authorization: YOUR-SECURITY-TOKEN' \
--get -X GET 'https://host.example.com/restApi/api/directoryObjects' \
--data-urlencode 'directoryobject=CN=My Group,OU=Groups,DC=example,DC=com' \
--data-urlencode 'properties=member,adm-Owners'

node.js

var https = require('https');

// Request parameters
var groupIdentifier = encodeURIComponent("CN=My Group,OU=Groups,DC=example,DC=com");
var propertiesToGet = "member,adm-Owners";
var requestPath = "/restApi/api/directoryObjects"
    + `?directoryobject=${groupIdentifier}`
    + `&properties=${propertiesToGet}`;

var options = {
    'method': 'GET',
    'hostname': 'host.example.com',
    'path': requestPath,
    'headers': {'Adm-Authorization': 'YOUR-SECURITY-TOKEN'}
};

// Make request
var req = https.request(options, res => {
    var data = [];

    res.on("data", chunk => {
        data.push(chunk);
    });

    res.on("end", () => {
        var body = Buffer.concat(data);
        console.log(body.toString());
    });

    res.on("error", error => {
        console.error(error);
    });
});
req.end();

Python

import requests
import json

baseUrl = "https://host.example.com/restApi"
endpoint = "/api/directoryObjects"

# Request parameters
requestUrl = baseUrl + endpoint
requestHeaders = {"Adm-Authorization": YOUR-SECURITY-TOKEN}
queryParams = {
    "directoryObject": "CN=My Group,OU=Groups,DC=example,DC=com",
    "properties": "member,adm-Owners"
}

# Make request
request = requests.get(requestUrl, headers=requestHeaders, params=queryParams)
response = json.loads(request.content)
print(response)

Response

HTTP Status code: 200 OK
Response body:

{
    "groupType": 1,
    "groupScope": 2,
    "membershipType": 0,
    "guid": "a7b63270-b8a4-4c34-b830-7e0d09f2e021",
    "dn": "CN=My Group,OU=Groups,DC=example,DC=com",
    "displayName": "My Group",
    "objectType": "group",
    "objectTypeCode": 3,
    "domainName": "example.com",
    "directoryType": 1,
    "properties": {
        "managedby": [
            "CN=John Smith,CN=Users,DC=example,DC=com",
            "CN=Anna Singer,CN=Users,DC=example,DC=com"
        ],
        "member": [
            "CN=John Smith,CN=Users,DC=example,DC=com",
            "CN=Richard Magnus,OU=Users,DC=example,DC=com",
            "CN=Ella Parkes,OU=Users,DC=example,DC=com"
        ]
    }
}

Get directory object

Query parameters

Name

Required

Type

Description

Request headers

Request body

Responses

Examples

Request

Response

Request

Response

Request

Response

Request

Response

See also