Copyright ©2023 by ESET, spol. s r.o.
ESET Connect was developed by ESET, spol. s r.o.
For more information visit https://www.eset.com.
All rights reserved. No part of this documentation may be reproduced, stored in a retrieval system or transmitted
in any form or by any means, electronic, mechanical, photocopying, recording, scanning, or otherwise without
permission in writing from the author.
ESET, spol. s r.o. reserves the right to change any of the described application software without prior notice.
Technical Support: https://support.eset.com
REV. 10/10/2023
1 About help 1 .........................................................................................................................................
2 Introduction 1 .......................................................................................................................................
2.1 What is an API 2 ............................................................................................................................
2.2 How the API works 2 ......................................................................................................................
3 Network Prerequisites 4 .......................................................................................................................
4 Release notes 5 ....................................................................................................................................
5 Getting started 5 ..................................................................................................................................
5.1 Create API User account 6 ..............................................................................................................
5.2 Authenticate API user 6 .................................................................................................................
5.3 Authorization 7 .............................................................................................................................
6 Using the API with Swagger UI 7 ..........................................................................................................
6.1 Working with Swagger UI 8 ............................................................................................................
7 Error codes 10 ......................................................................................................................................
8 Pagination 11 .......................................................................................................................................
9 Multitenancy 11 ...................................................................................................................................
10 Rate limits 12 .....................................................................................................................................
11 ESET PROTECT Cloud API 12 ..............................................................................................................
1
About help
This guide was written to help you get familiar with ESET Connect and provides instructions to use it.
For consistency and to help prevent confusion, the terminology used throughout this guide is based on the ESET
Connect parameter names. We also use a set of symbols to highlight topics of specific interest or significance.
Notes can provide valuable information, such as specific features or a link to a related topic.
This requires your attention and it should not be skipped. Usually, it provides non-critical but significant
information.
Critical information you should treat with increased caution. Warnings are placed specifically to deter you
from committing potentially harmful mistakes. Please read and understand text placed in warning brackets,
as it references highly sensitive system settings or something risky.
Example scenario that describes a user case relevant for the topic where it is included. Examples are used
to explain more complicated topics.
Convention Meaning
Bold type Names of interface items such as boxes and option buttons.
Italic type
Placeholders for information you provide. For example, filename or path means you type the
actual path or a name of file.
Courier New Code samples or commands.
Hyperlink Provides quick and easy access to cross-referenced topics or external web location. Hyperlinks
are highlighted in blue and may be underlined.
%ProgramFiles%
The Windows system directory which stores installed programs of Windows and others.
• Online Help is the primary source of help content. The latest version of Online Help will automatically be
displayed when you have a working internet connection.
• Topics in this guide are divided into several chapters and sub-chapters. You can find relevant information
by using the search field at the top.
• The ESET Knowledgebase contains answers to the most frequently asked questions, as well as
recommended solutions for various issues. Regularly updated by ESET technical specialists, the
Knowledgebase is the most powerful tool for resolving various types of problems.
• The ESET Forum provides ESET users with an easy way to get help and to help others. You can post any
problem or question related to your ESET products
Introduction
Welcome to ESET Connect Documentation.
The ESET Connect is an API gateway between a client and a collection of ESET backend services. ESET Connect acts
as a reverse proxy to accept all application programming interface (API) calls, aggregate the various services
required to fulfill them and return the appropriate result.
ESET APIs and future API integrations built on top of the API Gateway will offer the possibility to automate
monitoring, security, and administration activities.
2
This documentation will help you understand how to start using the API and API integrations, including
authentification, construction of API endpoint URIs, response status codes, error handling, pagination and rate
limits.
What is an API
What is an API?
API, or Application Programming Interface, is the intermediary software that allows two other programs to
communicate. The data transferred through the API is raw data that needs to be interpreted. You can think of the
API as a messenger that sends out calls and receives responses. The separation of the API from its
implementation allows programs written in one programming language to use a library written in a different
programming language.
Web APIs are interfaces for interactions between a user application on the front end (for example, Swagger UI)
and an application on the back-end (for example, ESET PROTECT Cloud). The back end is a remote server that
receives requests and sends responses. The API is an architectural approach that aims to provide a program
interface for a set of services to different applications that serve different consumer needs.
Security
The API also provides a security layer for the communication between the client and server. It simplifies
programming by showing only the objects and actions of the back end program that the user needs to interact
with.
ESET Connect APIs use unique temporary tokens that are included in each call to prove the user's identity.
Using the API
The API simplifies programming by exposing only the objects or actions the developer needs to interact with.
Implementation of API calls to your local application (for example, Postman or similar program and a custom-
made interface) can help you automate interactions with the ESET Connect APIs.
How the API works
About the API
The API facilitates calls from the client and responses from the server. The API service communicates with the
application. The application also has access to the application's database. This separation helps to secure the
communication process by not exposing the database to requests directly.
3
API call types
There are several types of API calls: GET, POST, PUT, DELETE. The GET, POST and DELETE calls are available in
ESET Connect APIs.
• GET calls do not consist of any input parameters. The request call cannot be modified; only executed.
• POST call is the call type used most frequently in the ESET Connect APIs.
Each call consists of:
• Call type
• Request URL
• Request header (can consist of the authentication token)
• Request body (contains data, especially with POST calls)
Server response structure
Each API call receives a response from the server. The response consists of the server response code and the
response itself formatted as data in JSON or XML.
The response consists of:
• Server code
• Response body
• Response headers
4
ESET Connect API uses the following sub-set of error codes:
OAuth Service
Error code Reason Returned message
4xx • empty request data
• null/empty/invalid grant_type
• null/empty client_id
• null/empty client_secret
• invalid credentials
• invalid token
415 Request data is not form content type
500 Unknown internal error (stack trace is present in log message)
503 IDS returns empty response
xxx when IDS returns unsuccessful response (HTTP code is copied from the IDS
response)
Domain services, connectors
Error code Explanation
HTTP 403 All user errors
HTTP 500 All backend-side errors
Status codes used in logs
Error code Explanation
0 (OK)
3 (InvalidArgument) invalid access token
7 (PermissionDenied) API not enabled for token
8 (ResourceExhausted) access token expired
13 (Internal) unspecified error
14 (Unavailable) error from IDS
16 (Unauthenticated) token validation failed
Network Prerequisites
Allow the below network prerequisites in your firewall for your API to work correctly.
Domain Description
eu.business-account.iam.eset.systems Location: Europe
eu.automation.eset.systems Location: Europe
eu.device-management.eset.systems Location: Europe
eu.incident-management.eset.systems Location: Europe
eu.policy-management.eset.systems Location: Europe
eu.installer-management.eset.systems Location: Europe
5
Domain Description
us.business-account.iam.eset.systems Location: USA
us.automation.eset.systems Location: USA
us.device-management.eset.systems Location: USA
us.incident-management.eset.systems Location: USA
us.policy-management.eset.systems Location: USA
us.installer-management.eset.systems Location: USA
Release notes
ESET Connect 2.0
Release date: October, 2023
• ADDED: Support for the following APIs:
oAuthentication
oApplication Management
oAutomation
oDevice Management
oIncident Management
oOS integration
oPolicy Management
oInstaller Management
Getting started
All APIs are RESTful HTTP endpoints.
All ESET APIs use standard authentication (JSON requests and responses with standard HTTP verbs).
Restriction of use:
ESET APIs are available only to users with valid ESET PROTECT license who are using ESET PROTECT console.
Only user accounts with sufficient access rights are allowed to use APIs.
Prerequisites:
1. Create an API user account
2. Authenticate the API user account
3. Authorization
6
Create API User account
How to create a user account that is allowed to use API:
1. In your ESET Business Account (or ESET MSP Administrator), create a new user account that you want to
use for API.
2. Under the Access Rights section, enable the slider bar next to Integrations.
3. Click Create to apply the changes.
4. Now, you can use this account for operations with API.
Authenticate API user
Once you Create a dedicated API user account, you need to Authenticate this user account with our Identity
Provider (IDS). This will provide you with time-limited and scope-limited authentication token. The authentication
token follows the JSON Web Token (JWT) standard.
How to obtain JSON Web Token (JWT):
Token expiration:
The JSON Web Token (JWT) is valid for 60 minutes. After this period, the user is required to perform a new
Authentication call to obtain a new token.
Once the Admin account removes the API user account, the rights for API calls this user can still
communicate with the API until his token expiration ends.
1. Authenticate with the API User account credentials using the OAuth API endpoint.
2. The token returned to you is used to authorize all subsequent API calls.
7
Swagger documentation for OAuth is available here.
It is the user's responsibility to store your API user credentials securely. If your API User credentials are lost
or stolen, an attacker will be able to call APIs on your behalf with your API user credentials and steal your
data or cause other forms of damage.
Authorization
To authorize a user, the user must meet the following criteria:
1. The API User account must have the right permissions to make an API call. The API User account follows the
access rights settings in the ESET Business Account or ESET MSP Administrator.
2. Authorization of the API User is performed by adding an Authorization header containing the JWT token to
an API call.
3. The authorization header must have the following format: Authorization: Bearer <JWT>
Using the API with Swagger UI
What is Swagger?
Swagger is an open-source software framework that helps developers design, build, document, and consume
RESTful Web services. You can interact with the API using the Swagger UI. The Swagger UI allows direct
connections to live APIs through a web page. You can create requests on the web page and explore API calls on
live data.
Swagger UI for ESET Connect APIs
The Swagger UI for ESET Connect APIs is available at Swagger UI for the EU and Swagger UI for the US. Swagger UI
provides complete pre-fabricated API calls. You only need to change the parameter values in the calls.
8
All Swagger (also all API) calls are executed on your real account with your real data. Do not use it as a
playground.
See the next chapter for more information on how to start learning in Swagger UI.
Working with Swagger UI
Log in
1.Navigate to the ESET Connect API Swagger UI page.
2.Click on /oauth/token call.
3.Click Try it out to start editing the call.
9
4.Fill in the client_id (Username) and client_secret (password).
5.Click Execute to send the call.
Save the authentication token
1.After the call is executed, you will receive a response that contains a token. You will need to use this
token to communicate with the server. Copy the token to the clipboard.
2.Navigate to an API you want to use and click Authorize at the top of the page.
3.Paste the access token string to the Value field and click Authorize.
10
4.The Swagger UI displays a confirmation of authorization. Click Close to close the window.
Error codes
ESET Connect API uses the following sub-set of error codes:
OAuth Service
11
Error code Reason Returned message
4xx • empty request data
• null/empty/invalid grant_type
• null/empty client_id
• null/empty client_secret
• invalid credentials
• invalid token
415 Request data is not form content type
500 Unknown internal error (stack trace is present in log message)
503 IDS returns empty response
xxx when IDS returns unsuccessful response (HTTP code is copied from the IDS
response)
Domain services, connectors
Error code Explanation
HTTP 403 All user errors
HTTP 500 All backend-side errors
Status codes used in logs
Error code Explanation
0 (OK)
3 (InvalidArgument) invalid access token
7 (PermissionDenied) API not enabled for token
8 (ResourceExhausted) access token expired
13 (Internal) unspecified error
14 (Unavailable) error from IDS
16 (Unauthenticated) token validation failed
Pagination
Most ESET APIs that return multiple resources wrap them in a "page" object. All APIs support a maximum page
size and a default page size of 100 items, but this limit varies between API endpoints. There are two different
styles of paging by different APIs that affect how pages are requested and the page's metadata in the returned
response.
ESET APIs support paging by offset:
The user requests a specific page of data starting from Page 1.
Multitenancy
ESET Connect APIs fully support the multitenancy model. Multiple tenants of one organization share the same API
infrastructure but operate in isolated environments.
12
To achieve your requirements for a specific resource or section, the required access rights must be granted to the
user in the ESET Business Account or ESET MSP Administrator. For more granular permissions, see the ESET
PROTECT Cloud console.
Rate limits
All ESET Connect APIs are rate-limited. (How many times you can call an API in a time window.)
If you call an API too often, you will see a response code 429 (Too many requests).
Time window Maximum number of calls
1 second 100 API calls
This rate limit fulfills the Denial of Service (DoS) protection.
The rate limit applies to each set of:
• API credentials
• Account
• Originating IP address
So, you cannot split your API calls between different API credentials from the same account or use the same API
credentials from different IP addresses to work around the rate limit.
ESET PROTECT Cloud API
Using the API with Swagger
Swagger UI provides complete pre-fabricated API calls:
• OAuth
• Automation
• Device Management
• Incident Management
Automation API calls support following client tasks:
• Isolate computer from network
• End computer isolation from network
• On-Demand Scan
13
• Shut down computer
• Stop managing (Uninstall ESET Management Agent)
• Software Uninstall (Third-party antivirus software)
• Operating system update
• Run command
REST APIs support only manual trigger type, which means starting ASAP. You cannot create tasks with other
trigger types (for example, starting periodically) in REST API. GetDeviceTasks record does not display any
other trigger types other than manual.
You can define task type via task.action.name attribute:
task.action.name task
StartNetworkIsolation Isolate computer from network
EndNetworkIsolation End computer isolation from network
OnDemandScan On-demand scan
ShutdownComputer Shut down computer
StopManaging Stop managing (Uninstall ESET Management Agent)
ThirdPartyAVRemove Software Uninstall (Third-party antivirus software)
SystemUpdate Operating system update
RunCommand Run command
In case of OnDemandScan and ShutdownComputer, you can configure additional task settings via
task.action.params:
{
"@type": "type.googleapis.com/Era.Common.DataDefinition.Task.OS.ShutdownComputer",
"restart": false,
"actions": {
"cancelAction": false,
"postpone": "OneHour"
}
}
14
• restart—if true, computer is restarted, if false computer is shutdown.
• actions—allowed actions for device users, postpone and cancel.
• cancelAction—true if user will be able to cancel the action or false if not.
• postpone—option to postpone action; possible postpone options are:
Cannot (Default value)
OneHour
ThreeHours
FiveHours
OneDay
ThreeDays
SevenDays
FifteenDays
TwentyDays
ThirtyDays
OnDemandScan parameters:
{
"@type": "type.googleapis.com/Era.Common.DataDefinition.Task.ESS.OnDemandScan",
"scanProfile": "InDepth",
"customProfileName": "",
"scanTargets": [
""
],
"cleaningEnabled": false,
"shutdownEnabled": false,
"shutdownLocked": false,
"powerActions": {
"cancelAction": false
"postpone": "OneHour",
}
}
15
• cleaningEnabled—true if cleaning is enabled.
• customProfileName—custom profile name for custom scan profile.
• scanProfile—scan profile that will be used during the scan; possible scan profiles are:
InDepth
InDepth
Smart
ContextMenu
MyProfile
Custom
•
scanTargets—list of scan targets. Empty list or an item equals 'eset://AllTargets', which means the full scan.
• shutdownEnabled—true if shutdown is enabled after scan completion.
• shutdownLocked—true if shutdown is enforced after scan (cannot be canceled).
• powerActions—allowed actions for device users, postpone and cancel; possible postpone options are:
Cannot (Default value)
OneHour
ThreeHours
FiveHours
OneDay
ThreeDays
SevenDays
FifteenDays
TwentyDays
ThirtyDays
You can see the result of OnDemandScan in task_runs[:]result. Example of scan result:
"result": {
"scannedTargets": "",
"scanned": 0,
"infected": 0,
"cleaned": 0,
"severity": "LOG_INFORMATION",
"@type": "type.googleapis.com/Era.Common.DataDefinition.Task.OnDemandScanResult"
}
• scannedTargets—list of scanned targets separated by semicolon.
• scanned—the number of scanned files.
• infected—the number of infected files.
• cleaned—the number of cleaned files.
• severity—severity of scan task.
SystemUpdate parameters:
{
"@type": "type.googleapis.com/Era.Common.DataDefinition.Task.OS.SystemUpdate",
"acceptEula": false,
"installOptionalUpdates": false,
"allowReboot": false,
"rebootActions": {
16
"cancelAction": false,
"postpone": "OneHour"
}
}
•
acceptEula—true if automatic EULA acceptance is allowed if it is requested by any of the updates (only Windows platform).
• installOptionalUpdates—true if optional updates should be also installed (only Windows platform).
• allowReboot—true if reboot is allowed if it is requested by any of the updates.
• cancelAction—true if user will be able to cancel the reboot action or false if not.
postpone—option to postpone reboot action; possible postpone options are:
Cannot (Default value)
OneHour
ThreeHours
FiveHours
OneDay
ThreeDays
SevenDays
FifteenDays
TwentyDays
ThirtyDays
RunCommand parameters:
{
"@type": "type.googleapis.com/Era.Common.DataDefinition.Task.OS.RunCommand",
"commandLine": "",
"currentDirectory": ""
}
commandLine—platform dependent command line that will be put into script file and executed.
currentDirectory—working directory for script file.
Task examples
Use the following examples with your own UUIDs and task settings. Device domain calls provide the UUID
of groups and devices.
On-demand scan
17
# On demand scan
{
"task": {
"description": "OnDemandScanASAP",
"targets": {
"devicesUuids": [
"11111111-2222-3333-4444-555555555555"
],
"deviceGroupsUuids": [
"11111111-2222-3333-4444-555555555555"
]
},
"displayName": "ScanAll",
"action": {
"params": {
"cleaningEnabled": True,
"@type": "type.googleapis.com/Era.Common.DataDefinition.Task.ESS.OnDemandScan",
"scanProfile": "InDepth",
"customProfileName": "",
"scanTargets": [
"eset://AllTargets"
]
},
"name": "OnDemandScan"
},
"triggers": [{
"manual": {
"expireTime": "2023-05-31T12:00:00Z"
}
}]
}
}
Shut down computer
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
/