ESET MSP Administrator EMA 2.0 API Owner's manual

ESET MSP Administrator 2 API

Guide

User guide

Click here to display the online version of this document

ESET MSP Administrator 2 API Guide was developed by ESET, spol. s r.o.

For more information visit https://www.eset.com.

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. 2023-10-10

1 Introduction to ESET MSP Administrator 2 API 1 ..................................................................................

1.1 What is an API? 2 ..........................................................................................................................

1.2 How the API works 2 ......................................................................................................................

1.3 Release Notes 4 ............................................................................................................................

2 Using the API with Swagger UI 10 ........................................................................................................

2.1 Working in Swagger UI 11 ..............................................................................................................

2.2 Renew the token 15 ......................................................................................................................

2.3 Log out of the Swagger UI session 17 ..............................................................................................

3 Using API 18 .........................................................................................................................................

3.1 List of functions 19 .......................................................................................................................

3.1 Operation 19 ..............................................................................................................................

3.1 BillingReport (category) 20 ..............................................................................................................

3.1 MyCompany 21 ...........................................................................................................................

3.1 My Company Selected Companies Only 23 .............................................................................................

3.1 Single Managed Company 24 ............................................................................................................

3.1 Divisions Under Selected Distributor 26 .................................................................................................

3.1 Company (category) 29 ..................................................................................................................

3.1 Delete 30 .................................................................................................................................

3.1 Detail 31 ..................................................................................................................................

3.1 Children 33 ...............................................................................................................................

3.1 Descendants 35 ..........................................................................................................................

3.1 Users 37 ..................................................................................................................................

3.1 Suspend 38 ...............................................................................................................................

3.1 Unsuspend 39 ............................................................................................................................

3.1 Create (category) 40 .....................................................................................................................

3.1 MSP 41 ....................................................................................................................................

3.1 Managed MSP 43 .........................................................................................................................

3.1 Customer 46 ..............................................................................................................................

3.1 Update (category) 48 ....................................................................................................................

3.1 MSP 48 ....................................................................................................................................

3.1 Managed MSP 52 .........................................................................................................................

3.1 Customer 55 ..............................................................................................................................

3.1 Ema1Mapping - migration 57 ............................................................................................................

3.1 CompanyId 58 ............................................................................................................................

3.1 SiteId 59 ..................................................................................................................................

3.1 LicenseId 60 ..............................................................................................................................

3.1 UserId 61 .................................................................................................................................

3.1 Enum (category) 61 ......................................................................................................................

3.1 EntityTypes 61 ............................................................................................................................

3.1 AvailableProducts 62 .....................................................................................................................

3.1 List of countries 64 .......................................................................................................................

3.1 User statuses 71 ..........................................................................................................................

3.1 PermissionTypes 71 ......................................................................................................................

3.1 LicenseStates 72 .........................................................................................................................

3.1 OperationStates 73 .......................................................................................................................

3.1 License (category) 74 ....................................................................................................................

3.1 Order 75 ..................................................................................................................................

3.1 UpdateQuantity 76 .......................................................................................................................

3.1 ExtendTrial 77 ............................................................................................................................

3.1 Suspend 78 ...............................................................................................................................

3.1 Unsuspend 79 ............................................................................................................................

3.1 Convert To Full 80 ........................................................................................................................

3.1 GetHistory 81 .............................................................................................................................

3.1 Detail 83 ..................................................................................................................................

3.1 ChangeProduct 85 ........................................................................................................................

3.1 GetPossibleProductChanges 86 ..........................................................................................................

3.1 Remove 88 ...............................................................................................................................

3.1 Search (category) 89 .....................................................................................................................

3.1 Licenses 89 ...............................................................................................................................

3.1 Users 92 ..................................................................................................................................

3.1 Companies 94 ............................................................................................................................

3.1 TermsOfUse 97 ...........................................................................................................................

3.1 Get 97 .....................................................................................................................................

3.1 Detail 98 ..................................................................................................................................

3.1 Accept 99 .................................................................................................................................

3.1 Token (category) 100 ....................................................................................................................

3.1 Get 101 ...................................................................................................................................

3.1 Renew 101 ...............................................................................................................................

3.1 Check 102 ................................................................................................................................

3.1 UsageReport (category) 103 ............................................................................................................

3.1 Products (category) 105 .................................................................................................................

3.1 AllCompanies 106 .......................................................................................................................

3.1 SelectedCompanies 108 .................................................................................................................

3.1 Monthly 110 ..............................................................................................................................

3.1 Daily 112 .................................................................................................................................

3.1 Categories (category) 114 ..............................................................................................................

3.1 AllCompanies 115 .......................................................................................................................

3.1 SelectedCompanies 118 .................................................................................................................

3.1 Monthly 119 ..............................................................................................................................

3.1 Daily 121 .................................................................................................................................

3.1 User 123 .................................................................................................................................

3.1 Current 124 ..............................................................................................................................

3.1 ChangePassword 126 ....................................................................................................................

3.1 Get User Details 127 .....................................................................................................................

3.1 Create 128 ...............................................................................................................................

3.1 Update 130 ...............................................................................................................................

3.1 Get Direct Accessible Children 132 .....................................................................................................

3.1 Version 134 ..............................................................................................................................

3.2 Example scenarios 134 ..................................................................................................................

3.2 C# scenarios 134 ........................................................................................................................

3.2 Prepare an environment 135 ............................................................................................................

3.2 Sample code 140 ........................................................................................................................

3.2 Code analysis 145 .......................................................................................................................

3.3 Troubleshooting API 152 ................................................................................................................

3.3 Error codes 152 ..........................................................................................................................

4 Help and support 159 ...........................................................................................................................

1

Introduction to ESET MSP Administrator 2 API

Welcome to the ESET MSP Administrator 2 API user guide. This document explains how to use and manage ESET

MSP Administrator 2 API. It also demonstrates the real-life usage of the API.

We use a uniform set of symbols to highlight topics of particular interest or significance. 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.

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.

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

• You can post your rating and/or provide feedback on a particular topic in help, click Was this information

helpful? to rate the article and add your comment.

Text boxes used in this guide:

Notes can provide valuable information, such as specific features or a link to some 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 case which describes a user case relevant for the topic where it is included. Examples are used to

explain more complicated topics.

Text conventions used in this guide:

Convention Meaning

Bold type Names of interface items such as boxes and option buttons.

Italic type

Placeholders for information you provide. For example,

file name

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.

2

Convention Meaning

%ProgramFiles%

The Windows system directory which stores installed programs of Windows and others.

What is an API?

API or Application Programming Interface, is the intermediary software that allows two other programs to

communicate, in this case, ESET MSP Administrator and your local application. 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 that occur between a user application on the front end (e.g. Swagger UI)

and an application on the back end (e.g. ESET MSP Administrator). 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 MSP Administrator 2 API uses 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 (e.g. Postman or similar program and a custom made

interface) can help you automate interactions with the ESET MSP Administrator portal.

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 and POST calls are available in ESET MSP

Administrator 2 API.

• 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 MSP Administrator 2 API.

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

Response code Code meaning

200 Success.

400 Bad request. The client request was invalid.

401 Unauthorized access. The access token is expired, not used or the credentials are invalid.

403 Forbidden action.

4

Response code Code meaning

403

code : 99

subCode : 1

We are sorry but it looks like we can't find the page you are looking for.

404 Resource not found.

500 Internal server error. The API call has triggered a faulty operation. Can be caused by an

unauthorized request.

503

code : 99

subCode : 2

Sorry, we are currently down for maintenance. ESET MSP Administrator API is being

updated to a newer version and will be back soon. Please try again later.

Release Notes

EMA 2 API version 1.0.54 (Service release)

Changelog

Release date: September 6, 2023

• New features and improvements

oMinor improvements

EMA 2 API version 1.0.53 (Service release)

Changelog

Release date: June 19, 2023

• New features and improvements

oCustomer is able add new ESET Protect Elite and ESET Protect Complete bundles into EMA2 account

• Bug-fixes

oFixed: None

EMA 2 API version 1.0.52 (Service release)

5

Changelog

Release date: April 4, 2023

• New features and improvements

oDetailed license usage report of entire hierarchy below MSP

• Bug-fixes

oFixed: No report is displayed for API/BillingReport/SingleManagedCompany

EMA 2 API version 1.0.51 (Service release)

Changelog

Release date: September 13, 2022

• Bug-fixes

oFixed: Minor bug fixes

EMA 2 API version 1.0.49 (Hotfix)

Changelog

Release date: July 13, 2022

• Bug-fixes

oFixed: Issue with computed license quantity after the Upgrade / Downgrade

oFixed: The expiration date of the license does not change after the Suspend and Unsuspend actions

oOther minor fixes

EMA 2 API version 1.0.48.1

6

Changelog

• New features and improvements

oEligible users can suspend and delete the company (the company stays available for billing and usage

reports for previous periods)

oEligible users can upgrade or downgrade a product

oImproved Trial licenses

oESET MSP Administrator 2 API Swagger was updated

• Bug-fixes

oMajor and minor bug fixes

EMA 2 API version 1.0.47.1

Changelog

• New features and improvements

oThe version of Swagger was updated

• Bug-fixes

oThe error displayed during updating VatID on Company was fixed

EMA 2 API version 1.0.46.1

Changelog

• Bug-fixes

oMissing days in the Daily usage report call were fixed

oOther bug fixes

7

EMA 2 API version 1.0.40

Changelog

• New features and significant changes:

oAll new and existing Managed MSPs are now allowed to use API

• Bug-fixes:

oSeveral bugs were fixed

EMA 2 API version 1.0.36

Changelog

• Fixed:

oLow performance on reports was fixed

oServer error in case of a specific product and categories calls was fixed

oMissing information in details of some bundle licenses was added

EMA 2 API version 1.0.34

Changelog

• New features and major changes:

oAll trusted Managed MSPs were allowed to used EMA2 API

• Fixed:

oSeveral bugs were fixed

Known Issues

• Minor known issues

8

EMA 2 API version 1.0.32.4 (Hotfix)

Changelog

• Fixed:

oBug-fixes

Known Issues

• Minor known issues

EMA 2 API version 1.0.32.1 (Hotfix)

Changelog

• Fixed:

oLicense usage fixes

Known Issues

• Minor known issues

EMA 2 API version 1.0.32 (Service Release)

Changelog

• Added:

oUsers can switch Managed MSP from trusted to untrusted and vice versa.

• Fixed:

oThe issue with incorrect usage after API integration was fixed.

oThe inability to create/edit MSP through API was fixed.

oIssues concerned with manage MSPs and licenses were fixed.

9

EMA 2 API version 1.0.28 (Service Release)

Changelog

• Added:

oTerms of Use for ESET Dynamic Threat Defense (EDTD)

• Fixed:

oInternal sever error appearing for call /api/Company/Update/customer

oOther minor fixes

EMA 2 API version 1.0.25

Changelog

• Added:

oLicense usage reports contain number of seats

oESET regional offices can find also the NetPrice value in billing reports

oMSP Managers can create customers for managed MSPs

• Fixed:

oIn-consistencies in billing reports

oOccasional internal server errors

oOther minor fixes

EMA 2 API version 1.0.21

Changelog

• Fixed:

oAn issue with disabled API for User / Company created by API was fixed

10

oError appearing while creating a user via Swagger was fixed

oNot working search of licenses by keyword was fixed

oAn issue with incorrect code/subcode appearing when the request for creating user is sent in a specific

case was fixed

Known Issues

• Error might appear when invalid data is entered in a license order

• Error might appear in response for user details

• Other minor known issues

EMA 2 API version 1.0.18

Known Issues

• o Some parameters may miss in the response.

oTrial extensions parameter may not display.

oChildren company e-mail may not display.

oDescription field in response may not display when the list of companies is called.

• Wrong response or error code is responded in minor cases.

oObsolete and Warning license states may display with the wrong description

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 MSP Administrator 2 API

The Swagger UI for ESET MSP Administrator 2 API is available at https://mspapi.eset.com/swagger/index.html.

Swagger UI provides complete pre-fabricated API calls. You only need to change the parameter values in the calls.

11

All Swagger (also all API) calls are executed on your real account with your real data. Do not use it as a

playground.

You can use Swagger UI to view your data in ESET MSP Administrator (the TEST version).

See the next chapter for more information to start learning in Swagger UI.

Working in the Swagger UI

Log in

1.Navigate to the ESET MSP Administrator 2 API Swagger UI page.

2.Click the /api/Token/Get call.

3.Click Try it out to start editing the call.

12

4.Replace the string values with your username and password.

5.Click Execute to send the call.

13

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.Click Authorize at the top of the page.

3.Paste the access token to the Value field and click Authorize.

NOTE: Since 4th Jan 2021, using the Bearer string is canceled in the Swagger UI. You still have to use (Bearer )

it in your own scripts, for example in your custom Python script.

14

4.The Swagger UI displays a confirmation of authorization. Click Close to close the window.

Execute calls

After the authorization is saved, you can execute other calls. The authorization token is included in each call

automatically by Swagger UI.

For example, you can execute the /api/User/Current call to get information about your current user:

1.Click the /api/User/Current call.

2.Click Try it out and Execute.

3.Swagger UI gives you a response with details about your current user. You can copy the company ID and

15

use it in other calls.

Renew the token

Each access token is only valid for one hour. Extend your session by renewing your token.

1.Click /api/Token/Renew > Try it out.

2.Enter the refresh token you obtained with your access token and click Execute.

16

3.In the response you receive a new access token and a new refresh token. Copy both of them to Notepad

or a similar application.

4.Click Authorize > Logout to stop using the current access token.

5.Type the word Bearer and your new access token to the Value field and click Authorize.

Page is loading ...

ESET MSP Administrator EMA 2.0 API Owner's manual

Related papers

Other documents