> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.trugrid.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# TruGrid API

### Overview
The TruGrid API enables customers and partners to interact programmatically with the TruGrid platform. 

**The TruGrid API enables the following functionality:**
* Manage [MFA settings for users](/en/article/how-admins-can-manage-mfa-on-new-design-1hybpp4/)
* Manage [User-Machine Assignments](/en/article/how-to-assign-users-to-computers-109hlex/)
* Initiate an [Active Directory sync to sync resources](/en/article/how-to-force-an-ad-refresh-18koeqs/)
* Manage allowed [UPN suffixes](/en/article/using-ad-upn-aliases-1lke09e/)
* Clear Machine [Associations](https://help.trugrid.com/en/article/how-to-use-resource-pooling-or-pooled-groups-aiqzqx/)
* Clear Application [Associations](https://help.trugrid.com/en/article/how-to-use-resource-pooling-or-pooled-groups-aiqzqx/)
* Force Active Directory [Refresh](https://help.trugrid.com/en/article/how-to-force-an-ad-refresh-18koeqs/)
* Force Application [Refresh](https://help.trugrid.com/en/article/how-to-use-remoteapp-kn0du1/)
* Enable [RDP over UDP for user](https://help.trugrid.com/en/article/trugrid-secure-rdp-rdp-over-udp-hm97ss/)
* Disable [RDP over UDP for user](https://help.trugrid.com/en/article/trugrid-secure-rdp-rdp-over-udp-hm97ss/)
* Fetch [Whitelist - IP](https://help.trugrid.com/en/article/how-to-whitelist-trugrid-outbound-traffic-on-the-firewall-1nniv4f/)
* Fetch [Whitelist - DNS](https://help.trugrid.com/en/article/how-to-whitelist-trugrid-outbound-traffic-on-the-firewall-1nniv4f/)
* Get User [Logon IP](https://help.trugrid.com/en/article/trugrid-analytics-h3cyks/)
* Set Machine [Associations](https://help.trugrid.com/en/article/how-to-use-resource-pooling-or-pooled-groups-aiqzqx/)
* Get Machine [Associations](https://help.trugrid.com/en/article/how-to-use-resource-pooling-or-pooled-groups-aiqzqx/)
* Get [MFA Status](https://help.trugrid.com/en/article/how-admins-can-manage-mfa-1hybpp4/)

|| We do plan to expand this functionality in the future. It does not provide any reporting functionality at this time. Please feel free to submit feedback on functionality you would like to see included in it.


###### How to obtain an API key

To utilize the TruGrid API, you will need an API key provisioned for your company. This key can be used for your primary domain and any customer domains (if you are an MSP). You can request an API key via TruGrid support, either via chat or by sending an email to help@trugrid.com .

When requesting an API key, please provide: 
* Your TruGrid admin login email address and domain name.
* Up to 15 external facing IP address the requests would initiate from. Only requests from those IP addresses will be processed.


###### API Interaction Rules

The below rules are applicable to all API endpoints listed in this document:
* API supports HTTP method POST
* Authentication header required (“api\_key”)
* To select domain for which request should be executed, domain DNS should be passed as query parameter called domainName

Example: https:// {api url}/{api\_route}?domainName=domain.com
* Other data required for API should be passed through the request body as JSON. The exact format will be listed in the specific API description.
* Request body cannot contain more than 100 elements.
* User’s UPN or domain’s DNS should be passed in corresponding format or else request will not be executed

| Authentication headed “api\_key” required for every endpoint. The {api url} can be obtained by reaching out to TruGrid support. 

||| If you receive an authorization failure when using the API, please let us know and confirm the external IP you are trying to access it from.

###### Turn ON MFA
* **Description:** API designed to turn ON MFA for users if it was previously disabled.
* **Request URI:** https:// {api url}/api/public/turnOnMfa
* **Query parameters:** domainName – DNS name of domain
* **Request Body:** list of user’s UPNs.


###### Turn OFF MFA
* **Description:** API designed to turn OFF MFA for users. It cannot be disabled for users with an Admin role.
* **Request URI:** https:// {api url}/api/public/turnOffMfa
* **Query parameters:** domainName – DNS name of domain
* **Request Body:** list of user’s UPNs.


###### Reset MFA
* **Description:** API designed to reset MFA for users. This cannot be done if the MFA is not set, or it is turned OFF.
* **Request URI:** https:// {api url}/api/public/resetMfa
* **Query parameters:** domainName – DNS name of domain
                                         resetPhone – parameter which indicates if phone number should be reset.                                 
                                         Can have 2 values: true or false. (If true then phone number will also be reset.)
* **Request Body:** list of user’s UPNs.


###### Create User-Machine Assignments
* **Description:** API designed to create assignment between user/user group and machine/machine group (same as Resource Assignments on TruGrid portal).
* **Request URI:** https:// {api url}/api/public/addUserMachineAssignment
* **Query parameters:** domainName – DNS name of domain
* **Request Body:** list of key-value pairs, where key is user’s UPN or user’s group name, and value is list of machines and/or machine’s group names. Keys should be unique.


###### Sync Newly Added Users
* **Description:** API designed to synchronize users added directly into TG-Users group in AD.
* **Request URI:** https:// {api url}/api/public/syncAddedAdUsers
* **Query parameters:** domainName – DNS name of domain.
* **Request Body:** list of user’s UPNs.

###### Sync Newly Added Machines
* **Description:** API designed to synchronize machines added directly into TG-Machines group in AD.
* **Request URI:** https:// {api url}/api/public/syncAddedAdMachines
* **Query parameters:** domainName – DNS name of domain
* **Request Body:** list of machine’s names.


###### Sync Newly Added User Groups
* **Description:** API designed to synchronize user’s groups added directly into TG-Users group in AD.
* **Request URI:** https:// {api url}/api/public/syncAddedAdUserGroups
* **Query parameters:** domainName – DNS name of domain
* **Request Body:** list of user’s group names.


###### Sync Newly Added Machine Groups
* **Description:** API designed to synchronize machine’s groups added directly into TG-Machines group in AD.
* **Request URI:** https:// {api url}/api/public/syncAddedAdMachineGroups
* **Query parameters:** domainName – DNS name of domain
* **Request Body:** list of machine’s groups names.


###### Add Allowed UPN Suffixes
* **Description:** API designed to add allowed UPN suffix for specific domain. Passed DNS names cannot match any of the already registered domains in TruGrid or already have been added as UPN suffix to another domain.
* **Request URI:** https:// {api url}/api/public/addUpnSuffix
* **Query parameters:** domainName – DNS name of domain
* **RequestBody:** list of domain’s DNS.


###### Clear Machine Associations
* **Description:** Endpoint to clear machine associations for specific domain. Can be done group-wise or for entire domain. Domain name should be passed as query parameter (domainName) in URL. To clear associations for specific groups – list of them should be passed into request body. To clear associations for all domains an empty list should be passed into request body.suffix to another domain.
* **Request URI:** https:// {api url}/api/public/clearMachineAssociations
* **Query parameters:** domainName – DNS name of domain
* **RequestBody:** application/JSON.

**Example:**
```
[] – clear for all groups in domain domain.com
[“group1”,“group2”] – clear for group1 and group2 for domain domain.com
```


###### Clear Application Associations
* **Description:** Endpoint to clear application associations for specific domain. Can be done group-wise or for entire domain. Domain name should be passed as query parameter (domainName) in URL. To clear associations for specific groups – list of them should be passed into request body. To clear associations for all domains an empty list should be passed into request body.
* **Request URI:** https:// {api url}/api/public/clearAppAssociations
* **Query parameters:** domainName – DNS name of domain
* **RequestBody:** application/JSON.

**Example:**
```
[] – clear for all groups in domain domain.com
[“group1”,“group2”] – clear for group1 and group2 for domain domain.com
```

###### Force Active Directory Refresh
* **Description:** Endpoint synchronizes all user and machine data from Active Directory for specific domain. Domain name should be passed as query parameter (domainName) in URL. Body of request should be empty.
* **Request URI:** https:// {api url}/api/public/RefreshActiveDirectory
* **Query parameters:** domainName – DNS name of domain
* **RequestBody:** Empty


###### Force Application Refresh
* **Description:** Endpoint synchronizes all published applications data from Active Directory for specific domain. Domain name should be passed as query parameter (domainName) in URL. Body of request should be empty.
* **Request URI:** https:// {api url}/api/public/RefreshApplications
* **Query parameters:** domainName – DNS name of domain
* **RequestBody:** Empty

###### Enable UDP
* **Description:** Endpoint enables UDP transport for RDP connections for specified users in a domain. Domain name should be passed as query parameter (domainName) in URL. Body of request should contain a list of user UPNs. If body is empty, UDP will be enabled for all users in the domain.
* **Request URI:** https://{api url}/api/public/EnableUdp
* **Query parameters:** domainName – DNS name of domain
* **Request Body:** JSON array of user UPN strings (optional — if empty, applies to all users)

###### Disable UDP
* **Description:** Endpoint disables UDP transport for RDP connections for specified users in a domain. Domain name should be passed as query parameter (domainName) in URL. Body of request should contain a list of user UPNs. If body is empty, UDP will be disabled for all users in the domain.
* **Request URI:** https://{api url}/api/public/DisableUdp
* **Query parameters:** domainName – DNS name of domain
* **Request Body:** JSON array of user UPN strings (optional — if empty, applies to all users)

###### Get IP Whitelist
* **Description:** API designed to retrieve the full IP whitelist for a specified domain. Returns a list of whitelisted IPs in JSON format, suitable for use in monitoring and firewall configuration workflows.
* **Request URI:** https:// {api url}/api/public/IpWhitelist
* **HTTP Method:** `GET`
* **Query parameters:**
    * `domainName` *(required)* – DNS name of the domain
* **Response Body:** JSON list of whitelisted IP addresses associated with the specified domain.

###### Get User Logon IP
* **Description:** API designed to retrieve user logon IP addresses for monitoring and alerting purposes. Supports querying by a single user UPN, multiple user UPNs, or an entire domain — returning the IP address(es) from each user's last login across web, desktop, and mobile. Results are returned in JSON format with appropriate HTTP status codes.
* **Request URI:** https:// {api url}/api/public/getUserLogonIp
* **Query parameters:**
    * `upns` – UPN of a single user or list of user UPNs
    * `domainName` – DNS name of the domain (returns last login IPs for all users in the domain)
* **Response Body:** JSON list of objects containing user UPN and their last login IP per client type (web, desktop, mobile).

###### Get External Resources DNS
* **Description:** API designed to retrieve a list of external resource DNS entries that should be whitelisted. Returns all DNS names required for proper whitelisting configuration in JSON format.
* **Request URI:** https:// {api url}/api/public/ExternalResources
* **HTTP Method:** `GET`
* **Query parameters:**
    * `domainName` *(required)* – DNS name of the domain
* **Response Body:** JSON list of external resource DNS entries required for whitelisting for the specified domain.

###### Set Machine Associations
* **Description:** Creates or updates user-to-machine associations within machine groups. Each item maps one user (by UPN) to one machine (by hostname) within a named group.
* **Request URI:** https://{api url}/api/public/SetMachineAssociations
* **HTTP Method:** `POST`
* **Auth:** api\_key header
* **Content-Type:** application/json - JSON array, max 100 items:
```json
[
  { "userUpn": "john@contoso.com", "groupName": "DesktopPool1", "machineName": "PC-01" },
  { "userUpn": "jane@contoso.com", "groupName": "DesktopPool1", "machineName": "PC-02" },
  { "userUpn": "bob@contoso.com", "groupName": "ServerPool", "machineName": "SRV-05" }
]
```
* **Fields:**
| Field | Type | Required | Description |
| userUpn | string | Yes | User principal name (email format) |
| groupName | string | Yes | Machine group name |
| **machineName** | string | Yes | Machine hostname |
* Status Values:
| Status | Meaning |
| Success. | Association created successfully |
| Success. Previous association with '{machineName}' replaced. | User had existing association in this group; updated to new machine |
| Error. Reason: Required data is missing. | One or more required fields are empty |
| Error. Reason: Group '{groupName}' not found in domain '{domainName}'. | Group does not exist |
| Error. Reason: Machine '{machineName}' not found in domain '{domainName}'. | Machine does not exist |
| Error. Reason: Machine '{machineName}' is not a member of group '{groupName}'. | Machine exists but is not in the specified group |
| Error. Reason: User '{userUpn}' not found in domain '{domainName}'. | User does not exist |
| Error. Reason: User '{userUpn}' is not assigned to group '{groupName}'. | User exists but is not assigned to the group |
| Error. Reason: Machine '{machineName}' is already associated with user '{otherUpn}' in group '{groupName}'. | Client-only group: machine is taken by another user |

* **Error Responses (400 Bad Request):**
•  Empty or null body: "Request body must contain at least one association."
•  More than 100 items: "Maximum 100 items per request."
•  Invalid UPN format: "Invalid UPN format encountered at {upn}."

* **Notes:**
•  In groups containing only client machines (non-server), each machine can only be associated with one user at a time
•  In groups containing at least one server, multiple users can be associated with the same machine
•  If a user already has an association in the group, it will be updated to the new machine
•  UPN format is validated before processing (must be valid email format)

###### Get Machine Associations
* **Description:** Retrieves existing machine associations filtered by either a group name or a user UPN. Exactly one filter must be provided (not both, not neither).
* **Request URI:** https:// {api url}/api/public/GetMachineAssociations?domainName={domainName}&groupName={groupName}  or  ...&userUpn={userUpn}
* **HTTP Method:** `GET` 
* **Fields:** 
| Parameter | Type | Required | Description |
| domainName | string | Yes | Domain DNS name |
| groupName | string | One of two | Filter by machine group name |
| userUpn | string | One of two | Filter by user UPN |
* **Error Responses (400 Bad Request):**
| Condition | Message |
| Both filters provided | Exactly one of 'groupName' or 'userUpn' must be provided. |
| Neither filter provided | Exactly one of 'groupName' or 'userUpn' must be provided. |
| Invalid UPN format | Invalid UPN format encountered at {upn}. |
| Group not found | Group '{groupName}' not found in domain '{domainName}'. |
| User not found | User '{userUpn}' not found in domain '{domainName}'. |

###### Get MFA Status

* **Description:** Retrieves the current MFA status and enrolled MFA method for users in a domain. Pass a list of user UPNs in the request body to check specific users, or an empty array `[]` to return the status of every user in the domain. Unknown users are reported per item in the response and do not fail the request.
* **Request URI:** https://{api` url}/api/public/GetMfaStatus?domainName={domainName}`
* **HTTP Method:** `POST`
* **Fields:**

| Parameter | Type | Required | Description |
| ---- |
| domainName | string | Yes | Domain DNS name (query string) |
| userNames | string[] (JSON body) | Yes (may be empty) | List of user UPNs to check. Send `[]` to return all users in the domain. Maximum 100 items per request. Blank entries are ignored; duplicates are collapsed (case-insensitive). |

* **Request Body Example:**

```json
["user1@contoso.com", "user2@contoso.com"]
```

* **Response (200 OK):** JSON array with one item per requested user (or per domain user when the body is empty).

| Field | Type | Description |
| ---- |
| username | string | User UPN |
| result | string | `Success.` when the user was found, otherwise `Error. Reason: User does not exist.` |
| mfaStatus | string | Current MFA state. See values below. `N/A` when the user was not found. |
| type | string | Enrolled MFA method. Populated only when `mfaStatus` is `MFA Enabled`, otherwise `N/A`. |

* **mfaStatus values:**

| Value | Meaning |
| ---- |
| MFA Pending Setup | No MFA record exists yet, or MFA is enabled but the user has not completed enrollment |
| MFA Enabled | MFA is enabled and enrollment is complete |
| MFA Reset or Pending Re-enrollment | MFA is enabled, was reset by an administrator, and the user has not re-enrolled |
| MFA Disabled | MFA is turned off for the user |
| N/A | User not found in the domain |

* **type values:**

| Value | Meaning |
| ---- |
| Authenticator | Authentication app |
| Phone | Text message (SMS) |
| Email | Email code |
| N/A | Not enrolled or user not found |

* **Response Example:**

```json
[
  { "username": "user1@contoso.com", "result": "Success.", "mfaStatus": "MFA Enabled", "type": "Authenticator" },
  { "username": "user2@contoso.com", "result": "Success.", "mfaStatus": "MFA Pending Setup", "type": "N/A" },
  { "username": "unknown@contoso.com", "result": "Error. Reason: User does not exist.", "mfaStatus": "N/A", "type": "N/A" }
]
```

* **Error Responses (400 Bad Request):**

| Condition | Message |
| ---- |
| Domain not found | Domain with given name does not exist. |
| Request body missing or JSON `null` | Body cannot be null |
| Request body is not a JSON array of strings | Wrong input type |
| More than 100 user names provided | You cannot pass more than 100 user names at one time. |
| `api_key` header missing | api\_key must be provided |

* **Other Responses:** `403 Forbidden` when the API key is invalid, not issued for this domain, or the caller IP is not on the key's allow-list.