Skip to main content

1E 9.x (on-premises)

PrincipalSearch

Entity - Role Based Access Control - Interrogates the User and Groups in Active Directory

Verb

Request

Notes

Permissions required

GET

/Consumer/PrincipalSearch/ {encoded search string}

Search string must be Base64 encoded

Returns a UserSearchItem class:

Return class

public class UserSearchItem
{
    UserName
    ExternalId
    Email
    FullName
}

Note: Only returns principals that are NOT already present in the Tachyon Principal table. The reason is that this API is intended to be used by the UI that adds Principals to Tachyon.

Note: Obsolete from 5.0 onwards. Use POST to /Consumer/PrincipalSearch instead

  • Read

Returns Unauthorized (401) if user does not have the required permissions.

POST

/Consumer/PrincipalSearch

Minimum API version 5.02

Searches for an active directory object matching the SearchText.

Request payload

{
    "SearchText": "user",
    "ObjectTypes": [
        "user",
        "group"
    ],
    "PageSize": 25,
    "Sort": {
        "Column": "displayname",
        "Direction": "ASC"
    }
}

Payload fields:

  • SearchText - text to search for. Mandatory field. Must not be empty.

  • ObjectTypes - types of AD/LDAP objects to search for. Allowed values are 'user' and 'group'. Mandatory field. Must contain at least one valid value.

  • PageSize - number of results to return from AD/LDAP. This limit is applied to the AD/LDAP search itself and you might be receiving even fewer results if any of those returned by the AD/LDAP search already exist within Tachyon. Optional parameter. Default value is 100.

  • Sort - sorting specification. Only sorting on a single column is supported. Allowed columns: cn, mail, sAMAccountName, description, objectSid, displayName. Allowed directions: "ASC", "DESC". If not provided default sorting is ascending on displayName.

Response

[
    {
        "PrincipalName": "1E\\User.Name",
        "ExternalId": "S-1-5-21-9999999999-888888888-7777777777-66666",
        "Email": "user.name@1e.com",
        "DisplayName": "User Name",
        "IsGroup": false
    }
]
  • Read

Returns Unauthorized (401) if user does not have the required permissions.

GET

/Consumer/PrincipalSearch/User/ {encoded search string}

Search string is a user name such as "DOMAIN\USER", and it must be sent encoded in Base64

Returns a UserSearchItem class:

Response

[
    {
        "PrincipalName": "1E\\User.Name",
        "ExternalId": "S-1-5-21-9999999999-888888888-7777777777-66666",
        "Email": "user.name@1e.com",
        "DisplayName": "User Name",
        "IsGroup": false
    }
]

Note: At this time, the API always returns a single user, but the result is an array in case future versions become able to return multiple users.

An empty array will be returned if the user is not found.

The API attempts to find the user in the Tachyon Principal table. Failing that, the groups of the user are listed from AD and matched against the tachyon Principal table. If the user belongs to a group that is a valid Tachyon Principal, then the user's information is returned.

  • Read

Returns Unauthorized (401) if user does not have the required permissions.

GET

/Consumer/PrincipalSearch/ GetMembers/{groupName}

Returns members (users and groups, but not computers) of a specified Active Directory group.

Name of the group must be base64 encoded

  • Read

Returns Unauthorized (401) if user does not have the required permissions.

GET

/Consumer/PrincipalSearch/ DisplayName/{accountName}

Returns display name.

  • Read

Returns Unauthorized (401) if user does not have the required permissions.

GET

/Consumer/PrincipalSearch/ WhoAmI

Minimum API version 3.1

Returns currently logged in user info.

Response Payload

{
  "PrincipalName": "domain\\user.name",
  "ExternalId": "S-1-5-21-12028960629-789336058-1343024091-20287",
  "Email": "user.name@domain.com",
  "DisplayName": "User Name",
  "Photo": "base64photo"
}

N/A

GET

/Consumer/PrincipalSearch/ Whois/{accountname}

Minimum API version 5.1

Looks up a user in the Active Directory using the account name provided, and returns extended information about the user.

Account name must be Base64 encoded. Use Url-Safe Base64 ('_' instead of '/', '-' instead of '+', remove trailing '=').

The account name format is expected to be DOMAIN\USER.

  • Read