User Management API Guide

GET User: API to get TruU user by UPN, Email, GUID or TUID
DELETE User: API to delete TruU user by GUID
GET Device: API to get TruU user by UPN, Email, GUID or TUID and device by device ID
DELETE Device: API to delete device by TruU user GUID and device ID

In addition, (with platform version 24.153) TruU has created two data APIs to query the platform for information about:

Users: The Users API will return the users and their enrolled devices
Assets: The Assets API will return the workstations and the enrolled accounts on those workstations (including user information)

At a high level, the User Management APIs require the Admin to do the following:

Create and OAuth Client through the Admin Console
Obtain a Bearer token using the OAuth credentials
Use the Bearer token in the authentication header when calling TruU APIs

NOTE: the APIs discussed in this guide are for user management only. If you are looking for documentation on using TruU APIs for authentication, please refer to the Custom SSO Adapter Guide

Step 1: Creating OAuth Clients

We will start by adding a “User Operations” OAuth Client in the Admin Console. This will create a new OAuth credential pair (a client ID and secret) that will be needed to access the API

Navigate to the “Integrations/OAuth Clients” tab on the TruU Admin Console
Click the (+) button
Select “User Operations”
Name the OAuth Client (e.g., Enrollment API)
Click Create
Click Download And Finish

Step 2: Use the OAuth Client to Call the API

As mentioned above, the User Operations API can be used to GET and DELETE Users and Devices. The example below explains how to use the Enrolled Users API Retrieving an OAuth Token Use the details from the configuration file downloaded when you provisioned a “User Operations” OAuth Client from your TruU admin console in order to retrieve a bearer token

POST [https://global.platform.truu.ai/oauth/token](https://global.platform.truu.ai/oauth/token)

The content-type for this POST request should be application/x-www-form-urlencoded Data

grant_type=client_credentials&scope=tenant-management-api-user&client_id=<OAuth Client ID>&client_secret=<OAuth Client Secret>

Curl Example

curl https://global.platform.truu.ai/oauth/token -d 'grant_type=client_credentials&scope=tenant-management-api-user&client_id=<OAuth Client ID>&client_secret=<OAuth Client Secret>’

Example Response

\{  
  "access_token": "eyJ…",
  "token_type": "Bearer",
  "expires_in": 7199,
  "scope": "tenant-management-api-user",
  "domain": "4a9de178-8be4-4bb0-aa4b-1239a9695627",
  "ver": "2.0",
  "jti": "HY6P2g0kHuISYuQylXZ-5Fzt2bE"
}

Use the value from the access_token field as the Bearer token. Curl Example Assume you have stored the value of access_token into variable TOKEN you can query for enrolled users as follows:

curl [https://global.platform.truu.ai/api/v1/system/enrolled/users/](https://global.platform.truu.ai/api/v1/system/enrolled/users/) -H "Authorization: Bearer ${TOKEN}"
\{  
  "page": 1,
  "next": null,
  "previous": null,
  "final": 1,
  "pageSize": 100,
  "count": 4,
  "results": [
    \{
      "tuid": "4aec2a38-9a39-4df1-96fb-557c35e0dc3d",
      "guid": "56aaedb0-4a8c-452b-ab61-a59b5db037bd",
      "displayName": "User Name",
      "userPrincipal": "[email protected]",
      "email": "[email protected]",
      "lastSynced": "2024-01-06T07:13:54.805219Z",
      "created": "2020-10-21T17:53:06.246723Z"
    },
    ...
  ]
}      

Enrolled Users API API Endpoint = https://global.platform.truu.ai/api/v1/system/enrolled/users/ The Enrolled Users API returns all users enrolled in your TruU tenant. These results include anyone who has enrolled a device (mobile application, desktop client, or FIDO2 hardware key) even if those devices have since been deleted (meaning a user must also be deleted from your TruU admin console to be excluded from the results of this API). Results are paginated and the API supports optional query parameters to filter by Email, User Principal Name, GUID, and/or TUID NOTE: the trailing slash must be included in the URL when querying this endpoint. Failing to do so will result in a 301 redirect HTTP response code with no results Supported HTTP Methods

Optional Query Parameters

upn
- User Principal NameFull matching only
- Case insensitive
email
- Email addressFull matching only
- Case insensitive
guid
- User identifier from directory
  - Active directory: objectGUID
  - Entra ID: id
  - Okta: id
- Full matching only
- Case insensitive
tuid
- TruU user ID
- Full matching only
- Case insensitive

Pagination Query Parameters

page
- Include this query parameter to fetch a specific page of results
- Page 1 will be returned by default if omitted

Query parameters may be combined as in the following example:

/api/v1/system/enrolled/users/?email=[[email protected]](mailto:[email protected])\&upn=[[email protected]](mailto:[email protected])

Required Authorization Header

Authorization: Bearer <token>

Response Content Type

application/json

Response Status Codes

Parsing API Responses The response contains a count field that describes how many users (0 or more) were found among enrolled users with the optional query parameter filters applied. If you wish to determine if a user is enrolled, you may simply query the endpoint with an appropriate query parameter filter and then refer to the count from the response Examples Retrieve all enrolled users

GET https://global.platform.truu.ai/api/v1/system/enrolled/users/

{
  "page": 1,
  "next": 2,
  "previous": null,
  "final": 2,
  "pageSize": 100,
  "count": 117,
  "results": [
    {
      "tuid": "ebcd0728-8fe7-4d1a-ad51-314692f49153",
      "guid": "30cbe1fe-4f92-42ba-9c29-eea2a23d707d",
      "displayName": "User One",
      "userPrincipal": "[email protected]",
      "email": "[email protected]",
      "lastSynced": "2024-01-11T16:56:40.313923Z",
      "created": "2023-11-01T06:16:40.297704Z"
    },
    {
      "tuid": "75e7cae5-ab2c-40e7-832e-97293a0b5d0d",
      "guid": "92e0286b-a435-4422-9aa1-5967c1db12ff",
      "displayName": "User Two",
      "userPrincipal": "[email protected]",
      "email": "[email protected]",
      "lastSynced": "2024-01-11T17:00:15.024443Z",
      "created": "2022-03-31T18:24:18.397688Z"
    },
    ...
  ]
}

Retrieve the 2nd page of all enrolled users

GET https://global.platform.truu.ai/api/v1/system/enrolled/users/?page=2

{
  "page": 2,
  "next": null,
  "previous": 1,
  "final": 2,
  "pageSize": 100,
  "count": 117,
  "results": [
    {
      "tuid": "4801df0d-c1cf-4fca-9034-653d8519f09a",
      "guid": "f29c03fb-f0c9-4083-8816-437e5408a85e",
      "displayName": "User X",
      "userPrincipal": "[email protected]",
      "email": "[email protected]",
      "lastSynced": "2022-12-08T18:31:35.655807Z",
      "created": "2022-10-17T19:37:19.519701Z"
    },
    {
      "tuid": "661b1cc1-87c2-4e77-bb06-7746418fb715",
      "guid": "107663d5-02f6-4eb5-87c8-953c58950ad8",
      "displayName": "User Y",
      "userPrincipal": "[email protected]",
      "email": "[email protected]",
      "lastSynced": "2022-11-24T14:50:26.347020Z",
      "created": "2022-01-21T18:40:28.644791Z"
    },
    ...
  ]
}

Query by email address

GET https://global.platform.truu.ai/api/v1/system/enrolled/users/[email protected]

{
  "page": 1,
  "next": null,
  "previous": null,
  "final": 1,
  "pageSize": 100,
  "count": 2,
  "results": [
    {
      "tuid": "6fdf91d0-95f0-4175-96f2-257cd7b8474d",
      "guid": "b10857e1-e8c0-40ee-85b7-30af22704096",
      "displayName": "User Name",
      "userPrincipal": "[email protected]",
      "email": "[email protected]",
      "lastSynced": "2024-01-03T17:05:42.254193Z",
      "created": "2018-07-16T21:04:29.182948Z"
    },
    {
      "tuid": "c74e61b4-2b95-4777-8ddf-b30e486bedc2",
      "guid": "2e39d8c7-7ae1-4dfc-a2d5-e3acfb1ca539",
      "displayName": "User Name - Admin",
      "userPrincipal": "[email protected]",
      "email": "[email protected]",
      "lastSynced": "2024-01-03T17:10:32.371213Z",
      "created": "2022-05-26T04:03:26.397433Z"
    }
  ]
}

Device Management API

API Endpoint = https://global.platform.truu.ai/api/v1/system/devices/ The TruU Device Management API retrieves information about enrolled devices and associated users. Supported HTTP Methods

Required Authorization Header

Authorization: Bearer <token>

Response Content Type

application/json

Response Status Codes

Parsing API Responses The response contains a count field that describes how many enrolled devices were found. Examples

GET https://global.platform.truu.ai/api/v1/system/devices/
{
  "page": 1,
  "next": 2,
  "previous": null,
  "final": 33,
  "pageSize": 25,
  "count": 825,
  "results": [
    {
      "deviceId": "a43674e1-850c-5f87-a5ef-83d66f699faa",
      "deviceName": "MacBook Air",
      "appVersion": "23.4.0(673)",
      "sdkVersion": "1.0",
      "lastHeardFrom": 1705327828000,
      "softwareIdentifier": "Version 13.6.3 (Build 22G436)",
      "notificationId": null,
      "appId": "com.truu.LoginHost",
      "type": "MAC_TPM",
      "active": true,
      "created": "2024-01-12T16:02:54.066886Z",
      "user": {
          "tuid": "323619f2-db00-45db-8c40-71f833f1a47d",
          "guid": "ef8e112f-fd1e-4010-b1b8-2913e472c982",
          "displayName": "User Name",
          "userPrincipal": "[email protected]",
          "email": "[email protected]",
          "lastSynced": "2024-01-12T16:27:31.064376Z",
          "created": "2023-01-02T13:11:57.920966Z"
      },
      "domain": {
        "key": "dbcc2f1d-aed8-4453-8f75-3542f722a752",
        "name": "Tenant Name",
        "domain": "domain"
      }
    },
    ...
  ]
}

User Management API

API Endpoint = https://global.platform.truu.ai/api/v1/system/domainusers/<guid>/ The TruU User Management API supports user and device deletion. Supported HTTP Methods

GET / DELETE

Required Path Value

guid
- User identifier from directory
  - Active Directory: objectGUIDEntra ID: idOkta: id Full matching only
- Case sensitive

Required Authorization Header

Authorization: Bearer <token>

Response Content Type

application/json

Response Status Codes

200 / 204

Examples Retrieve a specific user by GUID

GET https://global.platform.truu.ai/api/v1/system/domainusers/ef8e112f-fd1e-4010-b1b8-2913e472c982/

{
  "tuid": "323619f2-db00-45db-8c40-71f833f1a47d",
  "guid": "ef8e112f-fd1e-4010-b1b8-2913e472c982",
  "displayName": "User Name",
  "userPrincipal": "[email protected]",
  "email": "[email protected]",
  "lastSynced": "2024-01-12T16:27:31.064376Z",
  "created": "2023-01-02T13:11:57.920966Z",
  "domain": {
	"key": "dbcc2f1d-aed8-4453-8f75-3542f722a752",
	"name": "Tenant Name",
	"domain": "domain"
  }
}

Retrieve a specific device for a user using the user’s GUID and device ID

GET https://global.platform.truu.ai/api/v1/system/domainusers/ef8e112f-fd1e-4010-b1b8-2913e472c982/devices/a43674e1-850c-5f87-a5ef-83d66f699faa/

{
  "deviceId": "a43674e1-850c-5f87-a5ef-83d66f699faa",
  "deviceName": "MacBook Air",
  "appVersion": "23.4.0(673)",
  "sdkVersion": "1.0",
  "lastHeardFrom": 1705327828000,
  "softwareIdentifier": "Version 13.6.3 (Build 22G436)",
  "notificationId": null,
  "appId": "com.truu.LoginHost",
  "type": "MAC_TPM",
  "active": true,
  "created": "2024-01-12T16:02:54.066886Z",
  "user": {
	"tuid": "323619f2-db00-45db-8c40-71f833f1a47d",
    "guid": "ef8e112f-fd1e-4010-b1b8-2913e472c982",
	"displayName": "User Name",
    "userPrincipal": "[email protected]",
	"email": "[email protected]",
    "lastSynced": "2024-01-12T16:27:31.064376Z",
	"created": "2023-01-02T13:11:57.920966Z"
  },
  "domain": {
    "key": "dbcc2f1d-aed8-4453-8f75-3542f722a752",
    "name": "Tenant Name",
    "domain": "domain"
  }
}

Delete a specific user device

DELETE https://global.platform.truu.ai/api/v1/system/domainusers/b10857e1-e8c0-40ee-85b7-30af22704096/devices/29d57fd7-7064-47cd-90f3-3a8a899a8644/
{
  "deviceId": "29d57fd7-7064-47cd-90f3-3a8a899a8644",
  "deviceName": "Pixel 5",
  "appVersion": "23.142.0",
  "sdkVersion": "23.142.0",
  "lastHeardFrom": 1704525233732,
  "softwareIdentifier": "34",
  "notificationId": "ezy_O305TSmpwu1JOhOuEA:APA91bGtnkdYQlhG3TsfHHJsC24a1kU4AVR1u-hn2-awucHnc8Zr9LOuyqg5ZIGJuEahGaU88G7mn05PmxTA4G7c1HhVvBEW1q6gFdYuc62LicIZUGs1u8dDNyVEqcA1fOj0TYaYdHd0",
  "appId": "com.truu.android.app",
  "type": "ANDROID",
  "active": false,
  "created": "2023-08-10T04:00:51.407853Z",
  "user": {
	"tuid": "6fdf91d0-95f0-4175-96f2-257cd7b8474d",
    "guid": "b10857e1-e8c0-40ee-85b7-30af22704096",
    "displayName": "User Name",
    "userPrincipal": "[email protected]",
    "email": "[email protected]",
    "lastSynced": "2024-01-06T07:13:56.077245Z",
    "created": "2018-07-16T21:04:29.182948Z"
  },
  "domain": {
	"key": "dbcc2f1d-aed8-4453-8f75-3542f722a752",
    "name": "Tenant Name",
    "domain": "domain"
  }
}

NOTE: the DELETE API response the active value is now false Delete a user and all associated devices

DELETE https://global.platform.truu.ai/api/v1/system/domainusers/2e39d8c7-7ae1-4dfc-a2d5-e3acfb1ca539/

The response will have HTTP status code 204 with no body. Users Data API API Endpoint = https://global.platform.truu.ai/data/api/v1/users/ The Users API will return the users and their enrolled devices NOTE: the trailing slash must be included in the URL when querying this endpoint. Failing to do so will result in a 301 redirect HTTP response code with no results

When using this API with no query parameters, all users will be returned and paginated at 25 users per page. The supported parameters for Users are:
- page: this is an integer which can be used to select which page you want to receive. (Note: if you enter a page that does not exist, the query will return an error.)
- userPrincipals: we support any number of UPNs (and are case insensitive in our search)
- emails: we support any number of email (and are case insensitive in our search)
- guids: we support any number of guids (and are case insensitive in our search)
NOTE: when using a single parameter (e.g., emails, you can include many emails) the query will be run as an OR. If you mix parameters, (e.g. emails and guids) the query will be run as an AND.

Supported HTTP Methods

Required Authorization Header

Authorization: Bearer <token>

Response Content Type

application/json

Response Status Codes

Examples Retrieve a set of users and their devices by GUIDs

GET https://global.platform.truu.ai/data/api/v1/users/?guids=bd0a51a1-dd1d-43bb-af80-d37126aea466&guids=066eefab-dec4-48a8-83bf-b585f93f20ad

{
  "page": 1,
  "next": null,
  "previous": null,
  "final": 1,
  "pageSize": 25,
  "count": 2,
  "results": [
    {
      "tuid": "93ebf78d-7878-4b95-86b3-0858e744758e",
      "guid": "bd0a51a1-dd1d-43bb-af80-d37126aea466",
      "displayName": "Barbara Taylor",
      "userPrincipal": "[email protected]",
      "email": "[email protected]",
      "lastSynced": "2024-03-18T14:54:42.329656Z",
      "created": "2023-09-24T14:54:42.329492Z",
      "devices": [
        {
          "deviceId": "59602811",
          "notificationsEnabled": false,
          "deviceName": "Barbara Taylor's MAC_TPM",
          "appVersion": "1.0.2",
          "type": "MAC_TPM",
          "lastHeardFrom": "2024-03-18T14:54:37.231000Z",
          "assuranceLevel": 100,
          "active": true
        }
      ]
    },
    {
      "tuid": "7470d1cb-2d7a-4758-a5db-88f1335efa8e",
      "guid": "066eefab-dec4-48a8-83bf-b585f93f20ad",
      "displayName": "Deborah Jackson",
      "userPrincipal": "[email protected]",
      "email": "[email protected]",
      "lastSynced": "2024-03-18T14:54:42.618366Z",
      "created": "2023-09-14T14:54:42.618207Z",
      "devices": [
        {
          "deviceId": "60957733",
          "notificationsEnabled": true,
          "deviceName": "Deborah Jackson's WINDOWS_TPM",
          "appVersion": "1.0.2",
          "type": "WINDOWS_TPM",
          "lastHeardFrom": "2024-03-18T14:54:36.954000Z",
          "assuranceLevel": 100,
          "active": true
        }
      ]
    }
  ]
}

NOTE: if you are using this API to determine the Assurance Level of the user’s device, the assurance level response will be a numeric value with the following mappings:

100 = Basic
300 = Trusted
500 = Certified

Assets Data API

API Endpoint = https://global.platform.truu.ai/data/api/v1/assets/ The Assets API will return the workstation and the enrolled accounts on that workstation (including user information) NOTE: the trailing slash must be included in the URL when querying this endpoint. Failing to do so will result in a 301 redirect HTTP response code with no results

When using this API with no query parameters, all assets will be returned and paginated at 25 assets per page. The supported parameters for Assets are:
- page: this is an integer which can be used to select which page you want to receive. (Note: if you enter a page that does not exist, the query will return an error.)
- ipAddresses: we support any number of IP addresses
- macAddresses: we support any number of MAC addresses

NOTE: when using a single parameter (e.g., ipAddresses, you can include many IPs) the query will be run as an OR. If you mix parameters, (e.g. ipAddresses and macAddresses) the query will be run as an AND. Supported HTTP Methods

Required Authorization Header

Authorization: Bearer <token>

Response Content Type

application/json

Response Status Codes

Examples Retrieve a set of users and their devices by GUIDs

GET https://global.platform.truu.ai/data/api/v1/assets/?ipAddresses=218.43.33.64&ipAddresses=24.237.68.37

{
	"page": 1,
	"next": null,
	"previous": null,
	"final": 1,
	"pageSize": 25,
	"count": 2,
	"results": [
		{
			"machineName": "testNewData",
			"displayName": "Test new Data",
			"type": "MAC_AGENT",
			"hardware": {
				"serialNumber": "exampleSerialNumber",
				"manufacturer": "Apple",
				"model": "Macbook Pro 16",
				"processor": "Intel i9",
				"biosVersion": "2"
			},
			"network": {
				"ipAddresses": [
					"145.202.33.77",
					"80.157.0.17",
					"230.241.152.3",
					"24.237.68.37",
					"106.44.74.9",
					"11.66.133.31"
				],
				"macAddresses": [
					"b4:4a:8a.64:71:e8",
					"a5:e6:f2:ea:77:14",
					"83:c0:73:57:8b:d3",
					"70:9e:ba:fa:22:0c",
					"37:61:42:63:1d:35"
				]
			},
			"lastHeardFrom": null,
			"devices": []
		},
		{
			"machineName": "fd1c5d98-6793-4c7a-b88f-07a198d35b56",
			"displayName": "Christopher Mitchell's Computer",
			"type": "WINDOWS_AGENT",
			"hardware": {
				"serialNumber": "5384",
				"model": "Surface Pro",
				"processor": "Intel i9",
				"biosVersion": "N22ET33W"
			},
			"network": {
				"ipAddresses": [
					"218.43.33.64",
					"246.64.33.170",
					"117.227.84.146",
					"205.231.96.164"
				],
				"macAddresses": [
					"3b:f0:6f:a2:c8:fa",
					"48:f4:37:ee:ca:10",
					"b3:24:b1:c7:d3:7d",
					"64:f6:33:f1:d9:02",
					"5c:21:65:31:b3:3f"
				]
			},
			"lastHeardFrom": null,
			"devices": [
				{
					"deviceId": "33922867",
					"notificationsEnabled": false,
					"deviceName": "Sharon Johnston's WINDOWS_TPM",
					"appVersion": "1.0.8",
					"type": "WINDOWS_TPM",
					"lastHeardFrom": "2024-03-18T14:54:38.948000Z",
					"assuranceLevel": 100,
					"active": true,
					"user": {
						"tuid": "ad6b25e5-7a7b-4491-88b6-3b06c6072c1e",
						"guid": "61f8951d-abc1-4f2c-bcad-0c3caca65419",
						"displayName": "Sharon Johnston",
						"userPrincipal": "[email protected]",
						"email": "[email protected]",
						"lastSynced": "2024-03-18T14:54:41.717521Z",
						"created": "2023-11-14T14:54:41.717351Z"
					}
				},
				{
					"deviceId": "40499772",
					"notificationsEnabled": true,
					"deviceName": "Carol Stewart's WINDOWS_TPM",
					"appVersion": "1.0.7",
					"type": "WINDOWS_TPM",
					"lastHeardFrom": "2024-03-18T14:54:38.378000Z",
					"assuranceLevel": 100,
					"active": true,
					"user": {
						"tuid": "70404917-1dd0-4582-a11b-0732f64a7345",
						"guid": "863e8d62-885a-406e-a29e-122823817123",
						"displayName": "Carol Stewart",
						"userPrincipal": "[email protected]",
						"email": "[email protected]",
						"lastSynced": "2024-03-18T14:54:41.936112Z",
						"created": "2022-11-07T14:54:41.935926Z"
					}
				},
				{
					"deviceId": "32917093",
					"notificationsEnabled": true,
					"deviceName": "Mary Diaz's WINDOWS_TPM",
					"appVersion": "1.0.8",
					"type": "WINDOWS_TPM",
					"lastHeardFrom": "2024-03-18T14:54:38.054000Z",
					"assuranceLevel": 100,
					"active": true,
					"user": {
						"tuid": "b7d4d174-8368-4642-954e-80f70c3f9e07",
						"guid": "770e45d6-04a7-4398-8e6c-ff76c210fcc6",
						"displayName": "Mary Diaz",
						"userPrincipal": "[email protected]",
						"email": "[email protected]",
						"lastSynced": "2024-03-18T14:54:42.165055Z",
						"created": "2022-08-10T14:54:42.164891Z"
					}
				}
			]
		}
	]
}

NOTE: if you are using this API to determine the Assurance Level of the Asset, the assurance level response will be a numeric value with the following mappings:

100 = Basic
300 = Trusted
500 = Certified.

NOTE: the Asset may have multiple enrollments (e.g. a shared machine with 2 enrolled users). The Assurance Level is not for the device but for the user account on the device

How to Determine Whether Agent is using FIDO2 or Cert based login MacOS Local Account Creation Control for ADE

FAQ: Knowledge Base

​Step 1: Creating OAuth Clients

​Step 2: Use the OAuth Client to Call the API

​Device Management API

​User Management API

​Assets Data API

Step 1: Creating OAuth Clients

Step 2: Use the OAuth Client to Call the API

Device Management API

User Management API

Assets Data API