--- title: "Drive Encryption 7.4.x Web API Scripting Reference Guide" slug: "drive-encryption-7-4-x-web-api-scripting-reference-guide-1" tags: ["Drive Encryption", "Reference"] updated: 2026-09-12T18:22:35Z published: 2026-09-12T18:22:35Z canonical: "docs.trellix.com/drive-encryption-7-4-x-web-api-scripting-reference-guide-1" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.trellix.com/llms.txt > Use this file to discover all available pages before exploring further. # Drive Encryption 7.4.x Web API Scripting Reference Guide # Introduction **Trellix Drive Encryption 7.x.x** introduces Web API commands that add scripting and automation capabilities to these management activities: - Add or remove a user(s) from a system(s) - Perform user directory management (Non LDAP) - Change a user password - Export disk encryption key(s) for a system - Generate a Challenge Response Code - Reset self recovery for a user > **Note** > > In this document, **Drive Encryption 7.x.x** refers to **Drive Encryption 7.1.x, 7.2.0, and above**. ## Purpose of this guide This guide provides the Web API commands that you need to configure, use, and maintain **Drive Encryption**. This guide is a companion document to the *Trellix ePolicy Orchestrator - On-prem Scripting Guide*. > **Note** > > The scripting functionalities of **Drive Encryption 7.2.x** are supported only from version **Trellix ePO - On-prem 5.3.x and above**. The *Trellix ePO - On-prem Scripting Guide* describes the **Trellix ePO - On-prem** Web API and how to use it. It also provides example scripts using the Python client. For more information about Web API basics, see the *Trellix ePO - On-prem Scripting Guide*. [2](/data-and-email/docs/drive-encryption-7-4-x-web-api-scripting-reference-guide-1#) | Introduction --- # Web API commands for **Drive Encryption** Scripts using the Web API can be run from any computer that can connect to the **Trellix ePO - On-prem** server. For security reasons, they should not be run on the same computer as the **Trellix ePO - On-prem** server itself. The Web API is used primarily for two purposes: - Scripting sequences of tasks - Performing simple tasks without using the user interface ## Referencing systems and branches The commands available through the **Drive Encryption** Web API and **Trellix ePO - On-prem** Web API commands, commonly need to reference a system or a branch within the **Trellix ePO - On-prem System Tree**. The following terms are used throughout this guide: - **Computer ID:** This term refers to a number (also known as a leafNodeId) that identifies the system in the **System Tree**. You can identify this number by using the EPOComputerProperties.ParentID attribute. This attribute is part of the system.find command output. - **Branch ID:** This term refers to a number that identifies a branch (also known as groupId) within the **Trellix ePO - On-prem System Tree**. You can identify this number by: - Locating a system through the system.find command, and inspecting the EPOBranchNode.AutoID attribute - Locating a System Tree group through the system.findGroup command, and inspecting the groupId attribute - **systemNode:** This is a Drive Encryption Web API command parameter that controls the meaning of nodeId. Its possible values are ‘True’ or ‘False’. - **nodeId:** This is a Drive Encryption Web API command parameter. The meaning of nodeId changes depending on the value of the systemNode parameter: - If systemNode = ‘True’: nodeId means Computer Id / leafNodeId - If systemNode = ‘False’: nodeId means Branch Id / groupId The following examples show how the standard **Trellix ePO - On-prem** Web API commands are used to obtain the Computer ID or Branch ID: ## Search by system To find information about system **TEST123**, run this remote command: https://myeposerver:8443/remote/system.find?searchText=TEST123&:output=xml?>. The output contains the following (among other output): ## [2](/data-and-email/docs/drive-encryption-7-4-x-web-api-scripting-reference-guide-1#) | Introduction --- ```plaintext OK: ``` ```plaintext ``` ```plaintext ``` ```plaintext ``` ```plaintext ``` ```plaintext 272 ``` ```plaintext ... ``` ```plaintext 58 ``` ```plaintext ``` ```plaintext ``` ```plaintext ``` ### [Locating System Tree branch / group ID](/data-and-email/docs/drive-encryption-7-4-x-web-api-scripting-reference-guide-1#) To find the **System Tree** group identifier, run this remote command: https://myeposerver:8443/remote/system.findGroups?searchText=?>. The output contains a list of all **System Tree** groups, with their groupId: ```plaintext OK: ``` ```plaintext groupId: 2 ``` ```plaintext groupPath: My Organization ``` --- Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide 5 ## [2](/data-and-email/docs/drive-encryption-7-4-x-web-api-scripting-reference-guide-1#page-2) | Introduction --- ```plaintext groupId: 3 ``` ```plaintext groupPath: My Organization\Lost&Found ``` # Using Web API commands for Drive Encryption A few Web API commands are more commonly used than others. Being familiar with their syntax will help you create scripts quickly. The following tables list the commonly used commands with their syntax and description. The examples in this guide are taken from different categories of tasks that show how scripting can help keep your **Drive Encryption** maintained and up-to-date. Before running any commands, you must authenticate with an **Trellix ePO - On-prem** server. > ⚠️ > > **Caution** > > If you use Python to change passwords or export machine keys, make sure that `CREATE_LOG_FILE` is not enabled in debug mode. When it is enabled, passwords and machine keys are logged to the file in plain text, making it a security risk. If you need to enable it, execute the command on a secure system, then make sure to shred the log file to prevent unauthorized users from accessing your passwords and machine keys. ## Add a user or a user group to a system or branch The **Drive Encryption** software can be activated on a client system only after adding a user and enforcing the required encryption policies correctly. Use the `eeadmin.assignUser` command to add a user or a user group to a system or branch in **Trellix ePO - On-prem**. [eeadmin.assignUser command](/data-and-email/docs/drive-encryption-7-4-x-web-api-scripting-reference-guide-1#eeadmin.assignUser) | Command | Syntax | Description | | --- | --- | --- | | eeadmin.assignUser | ```plaintext eeadmin.assignUser systemNode=<> nodeId=<> dn=<> [recursive=<>] [ldapServerName=<>] ``` | Specify **systemNode='True'** to indicate that `nodeId=computer Id` refers to an **Trellix ePO - On-prem System**, or **systemNode='False'** to indicate that `nodeId=branch Id` refers to a **Trellix ePO - On-prem Branch**. Pass the Distinguished Name (DN) of the LDAP User or User Group to add accordingly. For LDAP Group addition, optionally specify: | 6 Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide [2](/data-and-email/docs/drive-encryption-7-4-x-web-api-scripting-reference-guide-1#) | Introduction --- | **Command** | **Syntax** | **Description** | | --- | --- | --- | | | | - `recursive='True'` to recursively add all subgroups, or - `recursive='False'` to avoid recursive addition (defaults to False) You must specify the LDAP server name, if more than one server is in use in your organization; otherwise it is optional. To confirm the node ID for a system, use this command: `remote/system.find?searchText=$($(SystemName))&:output=xml` You can search by name, IP address, MAC address, user name, AgentGUID, or tag. To check for node ID duplicates, use this command: `EPOComputerProperties.ParentID.count` | # Remove a user or a user group from a system or branch Use the `eeadmin.deassignUser` to remove a user or a user group from a system or branch in **Trellix ePO - On-prem**. [eeadmin.deassignUser command](/data-and-email/docs/drive-encryption-7-4-x-web-api-scripting-reference-guide-1#) | **Command** | **Syntax** | **Description** | | --- | --- | --- | | eeadmin.deassignUser | `eeadmin.deassignUser` `systemNode=<>` `nodeId=<>` `dn=<>` `dnType=<>` | Specify `systemNode='True'` to indicate that `nodeId=computer Id` refers to an **Trellix ePO - On‑prem** System, or `systemNode='False'` to indicate that `nodeId=branch Id` refers to an **Trellix ePO - On‑prem** Branch. Pass the DN of the user or user group to remove accordingly. Specify whether the DN refers to a User, User Group, or Organizational Unit (OU) (1=User, 2=User Group,3=OU). This is required to make sure that you do not have to run an overloaded LDAP query to process this command. | [2](/data-and-email/docs/drive-encryption-7-4-x-web-api-scripting-reference-guide-1#) | Introduction --- # Change a user password Resetting or changing a remote user's password token requires an authorization from administrator. The eeadmin.changeUserPassword command allows the administrator to change the user password remotely. [eeadmin.changeUserPassword command](/data-and-email/docs/drive-encryption-7-4-x-web-api-scripting-reference-guide-1#) | **Command** | **Syntax** | **Description** | | --- | --- | --- | | eeadmin.changeUserPassword | eeadmin.changeUserPassword userDn=<> newPassword=<> [oldPassword=<>] | If you specify the correct old password, the user's password is changed successfully. If you specify an incorrect old password, the command fails and leaves the existing password unchanged. If you don't specify the old password, users are reinitialized, leading to the loss of token, logon, Single-Sign-On (SSO), Self-Recovery, and password history data. This requires the users to reinitialize their data at next logon. | ## Export disk encryption key(s) for a system The purpose of encrypting the client's data is to control access to the data by controlling access to the encryption keys. These keys are referred to as Machine Keys. Each system has its own unique Machine Key. The Machine Key is stored in **Trellix ePO - On‑prem** database to be used for client recovery when required. Use the eeadmin.exportMachineKey command to remotely export disk encryption key(s) for a system. [eeadmin.exportMachineKey command](/data-and-email/docs/drive-encryption-7-4-x-web-api-scripting-reference-guide-1#) | **Command** | **Syntax** | **Description** | | --- | --- | --- | | eeadmin.exportMachineKey | eeadmin.exportMachineKey [machineIdOrName=<>] [keyCheck=<>] [oldKeys=<>] | A system may be activated and deactivated multiple times. Each activation produces a new disk encryption key. Specify the following: - the **Trellix ePO - On‑prem** System ID or **Trellix ePO - On‑prem** System Name to export disk encryption key(s) for a specific system, or - a disk Key‑Check value to look up the encryption key related to the disk | [2](/data-and-email/docs/drive-encryption-7-4-x-web-api-scripting-reference-guide-1#) | Introduction --- | **Command** | **Syntax** | **Description** | | --- | --- | --- | | | | > ![Blue note icon — small pencil in a blue square](https://cdn.us.document360.io/0d453a50-e1da-4d4a-9409-fea7959614d8/Images/Documentation/drive-encryption-7.4.x-web-api-scripting-reference-guide_page_0009_img_01.png?sv=2026-02-06&spr=https&st=2026-11-22T14%3A54%3A33Z&se=2026-11-22T15%3A54%3A33Z&sr=c&sp=r&sig=LVNxoN0qWlGhJUgR0OC6%2F%2FHu%2BLnuzjz3Fn8nhp2jRiM%3D) > > **Note:** This lookup might take some time and the Key-Check value can be obtained for a disk from DETech. The encryption key of a disk might not be the same as the encryption key of a system. This is applicable when the disk is removed from the (encrypted) system prior to a deactivation/reactivation. Specify `oldKeys='True'` to export all disk encryption keys related to the system. | ## Generate a Challenge Response Code If the user's password or logon tokens have been lost, you need to perform administrator recovery on the client computer to recover the user or system. User calls the administrator to perform the administrator recovery, and provides the Challenge Code. The administrator initiates the **Trellix ePO - On-prem** Scripting API to generate the Challenge Response Code. A valid Response Code is supplied by the scripting API to the administrator. When typing the Response Code, access is granted to the Client system. Use the `eeadmin.administratorRecovery` command to generate the Challenge Response Code. There are four different administrator recovery types: - machineRecovery='1' - resetUserToken='2' - unlockDisabledUser='3' - reserUserToPasswordToken='4' [machineRecovery recovery type](/data-and-email/docs/drive-encryption-7-4-x-web-api-scripting-reference-guide-1#) | **Description** | **Details** | | --- | --- | | Description | Specify `recoveryType='1'`, to perform Machine Recovery. | [2](/data-and-email/docs/drive-encryption-7-4-x-web-api-scripting-reference-guide-1#) | Introduction --- | **Description** | | | --- | --- | | . a d m i n i s t r a t o r R e c o v e r y C o d e = <> r e c o v e r y | | --- 10 Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide [2](/data-and-email/docs/drive-encryption-7-4-x-web-api-scripting-reference-guide-1#) | Introduction --- | Syntax | Description | | --- | --- | | | | [**resetUserToken recovery type**](/data-and-email/docs/drive-encryption-7-4-x-web-api-scripting-reference-guide-1#) | Description | | --- | | Specify recoveryType='2' and pass the Distinguished Name (DN) of the user, to perform the Reset User Token Recovery. | --- Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide 11 ## [2](/data-and-email/docs/drive-encryption-7-4-x-web-api-scripting-reference-guide-1#) | Introduction --- | **Summary / Description** | | --- | | ```plaintext R e c o v e r y c h a l l e n g e C o d e = < > u r e c o v e r y T y p e = < > u ``` | --- 12 Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide [2 | Introduction](/data-and-email/docs/drive-encryption-7-4-x-web-api-scripting-reference-guide-1#) --- | **Syntax** | **Description** | | --- | --- | | ```plaintext serverDn = <> ``` | | [unlockDisabledUser recovery type](/data-and-email/docs/drive-encryption-7-4-x-web-api-scripting-reference-guide-1#) | **Syntax** | **Description** | | --- | --- | | ```plaintext recoveryType='3' ``` | Specify `recoveryType='3'` and pass the Distinguished Name (DN) of the user, to perform the Unlock Disabled User Recovery. | --- Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide13 ## 2 | Introduction --- | Symmetric | Description | | --- | --- | | symmetricChallengeCode = <> userDn | | --- 14 Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide ## 2 | Introduction --- | Syntax | Description | | --- | --- | | = | | | < | | | > | | **resetUserToPasswordToken recovery type** | Syntax | Description | | --- | --- | | | Specify recoveryType='4' and pass the Distinguished Name (DN) of the user, to perform the Reset User To Password Token Recovery. | --- Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide 15 ## [2](/data-and-email/docs/drive-encryption-7-4-x-web-api-scripting-reference-guide-1#) | Introduction --- | **Parameter** | **Description** | | --- | --- | | a l l e n g e C o d e = < > r e c o v e r y T y p e = < > u s e r D n = < > | | 16 Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide [2](/data-and-email/docs/drive-encryption-7-4-x-web-api-scripting-reference-guide-1#) | Introduction --- # Reset self recovery for a user The client user's self-recovery details can be reset remotely, then the user can enroll the self-recovery details with new self-recovery answers. Use the `eeadmin.resetSelfRecovery` command to reset your self recovery details. [eeadmin.resetSelfRecovery command](/data-and-email/docs/drive-encryption-7-4-x-web-api-scripting-reference-guide-1#) | Syntax | Description | | --- | --- | | ```plaintext eeadmin.resetSelfRecovery ``` | Pass the Distinguished Name (DN) of the user to reset your self recovery token. | ## [2](/data-and-email/docs/drive-encryption-7-4-x-web-api-scripting-reference-guide-1#) | Introduction --- | Description System idn | | --- | | > | --- | 18 | Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide | | --- | --- | [3](/data-and-email/docs/drive-encryption-7-4-x-web-api-scripting-reference-guide-1#) | Introduction --- # User Directory Management (Non LDAP) The User Directory feature utilizes the LDAP Sync extension and provides the ability for **Drive Encryption** to use users/groups from the User Directory (using the UserDirectory.zip extension). ## Web API commands for the User Directory Once you install the UserDirectory.zip extension into the **Trellix ePO - On-prem** server, you can create users and groups, and manage them using these Web API commands, without requiring to register an LDAP server in **Trellix ePO - On-prem**. This allows the EEPC 5.1.x or above standalone users, who are not part of any LDAP server to be migrated to **Drive Encryption 7.x**. | **Syntax** | **Command** | | --- | --- | | itemId=<> | Refers to the item(s) whose attributes need to be edited. | | stringAttributes=<> | Name of the attribute(s) that needs to be edited or added. | --- Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide19 ## 3 | Introduction --- | Syntax and | Command | | --- | --- | | i | | | b | | | u | | | t | | | e | | | i | | | t | | | e | | | m | | | D | | | n | | | = | | | < | | | > | | | o | | | r | | | i | | | t | | | e | | | m | | | D | | | n | | | = | | | < | | | > | | | s | | | t | | | r | | | i | | | n | | | g | | | A | | | t | | | t | | | r | | | i | | | b | | | u | | | t | | | e | | --- 20Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide [3](/data-and-email/docs/drive-encryption-7-4-x-web-api-scripting-reference-guide-1#) | Introduction --- | **Syntax** | **Command** | | --- | --- | | ```plaintext s = < > ``` | **parentDn/parentId=<>** — The Parent DN/ ID can be taken from the database or the user interface. **itemName=<>** — Name of the item **itemType=<>** — User or Group | ## 3 | Introduction --- | **Syntax and** | | --- | | | | `itemDn/itemId=<>` | — Refers to the item that needs to be deleted. | | --- | --- | --- 22 Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide ## 3 | Introduction --- | Syntax and | | --- | | | `itemDn/itemId=<>` — Refers to the item whose attribute details are retrieved. `attribName=<>` — Name of the attribute. Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide 23 ## [3](/data-and-email/docs/drive-encryption-7-4-x-web-api-scripting-reference-guide-1#) | Introduction --- | Syntax and | | | --- | --- | | r y . g e t A t t r i b u t e i t e m D n / i t e m I d = < > a t t r i b N a m e | | --- 24 Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide ## [3](/data-and-email/docs/drive-encryption-7-4-x-web-api-scripting-reference-guide-1#) | Introduction --- | **Syntax and** | | | --- | --- | | ```plaintext e = < > ``` | **itemDn/itemId=<>** — Refers to the item whose attribute needs to be deleted. **attribName=<>** — Name of the attribute that needs to be deleted. | Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide25 ## 3 | Introduction --- | **Syntax and** | | --- | | | | `itemId/itemDn=<>` | — Refers to the item that needs to be enabled/disabled. | | --- | --- | | `enabled=<>` | — True enables the item. False disables the item. | --- 26 Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide ## 3 | Introduction --- | Syntax and | | | --- | --- | | | | | `itemDn/itemId=<>` | — Refers to the item that needs to be moved. | | --- | --- | | `parentFqdn/parentId=<>` | — Parent FQDN/ ID can be taken from the database or the user interface. | --- Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide27 ## 3 | Introduction --- | **Syntax and** | | --- | | ```plaintext i r e c t o r y . m o v e I t e m D n / i t e m I d = < > p a r e n t F ``` | --- | 28 | | Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide | | --- | --- | --- | ### [3](/data-and-email/docs/drive-encryption-7-4-x-web-api-scripting-reference-guide-1#) | Introduction --- | **Syntax and** | | --- | | ```plaintext itemDn/itemId=<> ``` ```plaintext newName=<> ``` | **itemDn/itemId=<>** — Refers to the item that needs to be renamed. **newName=<>** — Refers to the new name for the item --- Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide 29 ## 3 | Introduction --- | **Syntax and** | | --- | | This command performs a search on the user directory. This command is different from the other commands with these 3 parameters, which are optional. - **rootDn or rootId** — The FQDN/ ID can be taken from the database or the user interface. - **searchString** — String criteria of the search. It returns all items that contain the search string. - **recursive** — This is either "True" or "False". It defines if this search should be done recursively. It is default to be False if any parameter is not set. | > **Note:** > > There are seven different scripts for the search item function. --- 30 Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide ## 3 | Introduction --- | Syntax and Command | | | --- | --- | | ```plaintext . s e a r c h I t e m s r o o t I d / r o o t D n = < > s e a r c h S t r i n g ``` | | --- Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide31 ### [3](/data-and-email/docs/drive-encryption-7-4-x-web-api-scripting-reference-guide-1#) | Introduction --- | **Syntax and Command** | | --- | | ```plaintext = < > recursive = < > ``` | # Help command You can use the Help command to get the structure for any command. For example, to export disk encryption key for a system, use the command `mc.help("eeadmin.exportMachineKey")` to get the structure of the command.