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
• Manage User-Machine Assignments
• Initiate an Active Directory sync to sync resources
• Manage allowed UPN suffixes
• Clear Machine Associations
• Clear Application Associations
• Force Active Directory Refresh
• Force Application Refresh
• Enable RDP over UDP for user
• Disable RDP over UDP for user
• Fetch Whitelist - IP
• Fetch Whitelist - DNS
• Get User Logon IP
• Set Machine Associations
• Get Machine Associations

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

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/ExternalResources
• HTTP Method: POST
• Auth: api_key header
• Content-Type: application/json - JSON array, max 100 items:

[
  { "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:

• Status Values:

• 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:

• Error Responses (400 Bad Request):

Updated on: 23/04/2026