Site icon Emsisoft Help

Automation guide: Setting up new customer workspaces via API

emsi

Emsisoft provides an extensive set of public web-APIs that can be used to automate frequently performed tasks, such as:

Our API is RESTful and returns JSON. New features are added regularly.

The Emsisoft API functionality generally reflects features of the MyEmsisoft Management Console and the Emsisoft Partner Portal.

Check out the Emsisoft API Documentation for full reference.

Prerequisites

Most Emsisoft API resources require an API-Key to authenticate. If you need an API-Key, please request one with your Emsisoft partner manager through the contact box located at the bottom right of this page.

API-Keys are assigned with user accounts. If your permission level enables access to specific functionality via the web portal, you can expect to get access to the same functionality via API, too.

Note that some API features are limited to registered Emsisoft Partners (e.g. assignment of stock licenses to workspaces) and some are only available for Emsisoft Distributors (e.g. on-the-fly creation of new licenses).

Create a new workspace

An Emsisoft workspace defines an entity that holds all devices of a single customer. A workspace is typically used to represent an organization, with protection and permission policy groups set up to mirror internal team/department structures.

As an Emsisoft partner, you can specify parameters like the workspace name, user roles and license information in a single API call, but it’s also possible to add workspace details step by step in individual API calls.

All-in-one API call

Save a text file create.json that contains all workspace details. Please replace sample data with your desired values.

{
  "name": "MyTestWorkspace",
  "customerEmail": "customer@email.com",
  "customerRole": "owner",
  "partnerRole": "admin",
  "billingContact": "Partner",
  "coupon": "XXX-YYY-ZZZ-356"
}

These example values will invite your customer to join the newly created workspace as an owner, add yourself as a workspace admin, assign one of your unused license coupons and make sure that Emsisoft will not reach out to your customers for renewals.

Alternatively, it’s also possible to assign a trial license for a specific product edition or add the workspace to your monthly MSP billing plan.

Run this POST command to perform the action:

curl -i -H "Api-Key: AAAAAAAA55AC4D61A2A741F1FFFFFFFF" 
     -H "Content-Type: application/json" 
     -d @create.json 
     https://api.emsisoft.com/v1/partner/workspaces/create

You should get a HTTP 200 status code in return to confirm that the workspace has been successfully created. Check for possible errors: HTTP 400 – Bad Request/Validation or logical error; HTTP 401 – Unauthorized. Insufficient permissions or API-key not provided.

Deploy the protection software

If your automation software has access to the device that needs protection, the quickest way to install the software is by requesting a tokenized installer download that installs and activates the product without any further user interaction required. Please also check out the available installer parameters for silent installations.

Get tokenized installer download link

Run this GET command:

curl -i -H "Api-Key: AAAAAAAA55AC4D61A2A741F1FFFFFFFF" 
     -H "Content-Type: application/json" 
     https://api.emsisoft.com/v1/workspaces/aaaaaaaa-4ebe-4d9c-9d43-ffffffffffff/install

You will get a response similar to this:

{
  "policyGroupGuid": "00000000-0000-0000-0000-000000000000",
  "isAutoRenewEnabled": false,
  "isWorkspace": true,
  "installToken": "000000-8f7d-42e0-a521-ffffffffffff",
  "downloadUrl": "https://dl.emsisoft.com/tagged/EmsisoftAntiMalwareWebSetup_000000-8f7d-42e0-a521-ffffffffffff.exe",
  "downloadX32Url": "https://dl.emsisoft.com/tagged/EmsisoftAntiMalwareSetup32_000000-8f7d-42e0-a521-ffffffffffff.msi",
  "downloadX64Url": "https://dl.emsisoft.com/tagged/EmsisoftAntiMalwareSetup64_000000-8f7d-42e0-a521-ffffffffffff.msi",
  "remoteDeployEnabled": false
}

The default (small) web installer is linked in field ‘downloadUrl’. Alternative downloads for specific use cases are provided, too. The token is unique to your default policy group in your workspace.

Important! Never share your tokens with the public, as it authorizes users to activate their software with your license key without further logins or license activation required.

Invite a user via email to install protection

Run this POST command:

curl -i -H "Api-Key: AAAAAAAA55AC4D61A2A741F1FFFFFFFF" 
     -H "Content-Type: application/json" 
     -d "{\"email\": \"example@email.com\"}" 
     https://api.emsisoft.com/v1/workspaces/aaaaaaaa-4ebe-4d9c-9d43-ffffffffffff/install/send-links

You should get a HTTP 200 status code in return to confirm that the download link was successfully sent to the specified user.

Conclusion

Using the Emsisoft API to automate common tasks is easy and doesn’t require extensive software development experience. Please check out the full API reference for more APIs. We will also extend the available features significantly over the next months.

If you have any questions or need assistance, please don’t hesitate to ask our support team.

Exit mobile version