Elements API Changelog

anesterov · January 2022

The WithSecure API changelog provides users with detailed updates, enhancements, and bug fixes related to the WithSecure Elements API integrations.

For the most recent updates, please click here to see the most recent changelog (only accessible for logged-in users).

To stay updated on future changes, we recommend bookmarking the discussion. Follow the steps outlined here to learn how to bookmark the discussion and be notified of any updates.

SergeH · April 2022

Endpoint Protection API

· New Security Events listing

Security Events provides extensive data that WithSecure engines detected. In addition to infections it reports security events generated by application control, Dataguard, tamper protection, browsing protection...The two new endpoints below provide listing by company or partner but also filtering (e.g. by device, by engine)

· https://connect.withsecure.com/api-reference/psb#get-/companies/-companyUuid-/security-events

· https://connect.withsecure.com/api-reference/psb#get-/partners/-partnerUuid-/security-events

· Infections listing are deprecated

Security Events contains infections and much more so the old infections endpoint are deprecated and should be replaced by replaced by Security Events at first opportunity

The following infections Endpoint will stop working by 29.10.2022

· https://connect.withsecure.com/api-reference/psb#get-/companies/-companyId-/infections

· https://connect.withsecure.com/api-reference/psb#get-/companies/-companyUuid-/computers/-computerId-/infections

· https://connect.withsecure.com/api-reference/psb#get-/partners/-partnerId-/infections

SergeH · May 2022

Provisioning API

· New url to reflect our new brand

Please update the following url at first opportunity.

Production:
- New url: https://commercial.connect.withsecure.com
- Deprecated url: https//boop.f-secure.com
Staging:
- New url: https://commercial-test.connect.withsecure.com
- Deprecated url: https://boop-test.f-secure.com

The existing whitelist will still apply.

The deprecated url will not be supported after 06.11.2022

· Get subscription

This new API call allows to get all the details of a subscription by querying with the key as described in https://connect.withsecure.com/api-reference/provisioning#get-/ws/rest/provisioning/v1/subscriptions/-subscription_key-

NicoL · May 2022

Provisioning API

· Register a Service Partner (SEP)

This API endpoint now return partnerUuid in the response. You may refer to API Reference in https://connect.withsecure.com/api-reference/provisioning#post-/ws/rest/provisioning/v1/seps

[Deleted User] · May 2022

Endpoint Protection API

Poll for security events

This new API endpoint is specifically meant for polling for changes in Security Events. By providing boundaries using server_timestamp query parameters clients have full control over the data set they are interested in. Moreover the data is sorted in the ascending order by the timestamp parameter allowing for easy replay of historical data also simplifying the polling for new events use cases.

Additional JavaScript code snippet is also attached to illustrate the advised approach to reading historical data and polling for the new events.

See: https://connect.withsecure.com/api-reference/psb#get-/accounts/-accountUuid-/security-events/polling

NicoL · June 2022

Provisioning API

· Get subscriptions by company uuid

This new API call allows to get the subscription details list under the specific licensee by querying with the unique identifier as described in https://connect.withsecure.com/api-reference/provisioning#get-/ws/rest/provisioning/v1/subscriptions-companyUuid--companyUuid--include_expired--include_expired-

· Get subscriptions by reference number

This new API call allows to get the subscription details list under the specific licensee by querying with the buyer's internal reference number as described in https://connect.withsecure.com/api-reference/provisioning#get-/ws/rest/provisioning/v1/subscriptions-buyer_assigned_account_id--buyer_assigned_account_id--include_expired--include_expired-

NicoL · August 2022

Provisioning API

· Get subscriptions by partner uuid

This new API call allows to get the subscription details list under the specific reseller by querying with the unique identifier as described in https://connect.withsecure.com/api-reference/provisioning#get-/ws/rest/provisioning/v1/subscriptions-partnerUuid--partnerUuid--include_expired--include_expired-

· Get subscriptions by buyer account id

This new API call allows to get the subscription details list under the specific partner by querying with the unique identifier as described in https://connect.withsecure.com/api-reference/provisioning#get-/ws/rest/provisioning/v1/subscriptions-buyer_account_id--buyer_account_id--include_expired--include_expired-

NicoL · September 2022

Provisioning API

New products are now supported in Provisioning API

FCEA: WithSecure™ Elements EDR for Computers

FCEN: WithSecure™ Elements EDR for Servers

FCKC: WithSecure™ Elements Vulnerability Management

NicoL · September 2022

Provisioning API

· Terminate subscription

This new API call allows to remove the subscription of licensee by using the key as described in https://connect.withsecure.com/api-reference/provisioning#delete-/ws/rest/provisioning/v1/subscriptions/-subscription_key--force--force-

Milosz · October 2022

Elements API

Elements API is a new API framework that will cover all Elements offer. For its launch it provides:

API Credentials UI where API credentials can be managed for all Elements solution. It allows to apply a policy to renew credential after a certain time or to delete unused credentials. API credentials are now independent of users.
Organization endpoint allowing a partner to list all its companies
Security Events endpoint allowing to list all security events including EDR incidents. That will replace the events endpoint in Endpoint Protection API.

Documentation:

Getting started guide: https://connect.withsecure.com/getting-started/elements
API reference: https://connect.withsecure.com/api-reference/elements#overview

dolatawojciech · November 2022

Elements API

Security Events endpoint now allows to fetch events also for partner organizations.

dolatawojciech · December 2022

Elements API

Changes in existing endpoints:

Organizations endpoint now has parameter 'type' which allows to fetch company or partner organizations. https://connect.withsecure.com/api-reference/elements#get-/organizations/v1/organizations

New endpoints:

Devices endpoint allows listing all devices under organization. https://connect.withsecure.com/api-reference/elements#get-/devices/v1/devices

This first release of Devices endpoint provides information related to the devices (IP address, serial number, UPN...) to allow correlation with other data sources in a SIEM/SOAR, as well as information related to the level of protection.

We are looking for customer feedback before adding even more data. Please provide your ideas through “My feedback” when you are logged in Elements Security Center, or directly through https://ideas.withsecure.com/ideas (same credentials that you are using to access Elements Security Center), under category "Elements API".

Endpoint Protection API: Devices endpoints are deprecated

The old devices endpoints are deprecated and should be replaced by replaced by the new Elements devices endpoints that provide more information.

The following devices endpoint will stop working by 30.05.2023:

Get all company computers report
Get all partner computers report
Get company computer details
List company computers
List partner computers

dolatawojciech · December 2022

Elements API

Changes in existing endpoints:

Devices and Security Events endpoints: parameter organizationId is now optional. If it is not present, default organization of authenticated client is used.
Organizations endpoint: added new optional organizationId parameter, now endpoint lists organizations belonging to requested organization (including itself if type matches). If parameter is not present, default organization of authenticated client is used. https://connect.withsecure.com/api-reference/elements#get-/organizations/v1/organizations

dolatawojciech · December 2022

Elements API

Changes in existing endpoints:

Security events endpoint supports filtering by engine (e.g. EDR) or severity (critical)
Security events endpoint supports a new engine: System events log. The type of events log sent must be configured from the EPP Profile

Endpoint Protection API

Security events endpoints are deprecated

The old security events endpoints are deprecated and should be replaced by the new Elements security events endpoints. https://connect.withsecure.com/api-reference/elements#get-/security-events/v1/security-events

The following security events endpoints will stop working by 30.06.2023:

List security events for a company
List security events for a partner
Poll for security events

Infections endpoints have been removed from documentation and will stop working at any time.

Milosz · January 2023

Endpoint Protection API

Companies endpoints are deprecated

Companies endpoints are deprecated. Clients should use instead Organizations endpoint from Elements API.

Support for Companies endpoint will end by 31.07.2023

dolatawojciech · February 2023

Elements API

Changes in existing endpoints:

Devices endpoint supports filtering by device serial number (https://connect.withsecure.com/api-reference/elements#get-/devices/v1/devices).

NicoL · February 2023

Provisioning API

Fixed the missing product in Provisioning API Get Subscription endpoints.

The following endpoint is now showing FCEC (WithSecure™ Elements EDR and EPP for Computers) in the response:

Get subscription by key
Get subscriptions by buyer account id
Get subscriptions by company uuid
Get subscriptions by partner uuid
Get subscriptions by reference number

Hubert_Szymanski · February 2023

Elements API

Changes in existing endpoints:

Devices endpoint: New fields were added to response with device type computer containing last software scan and install timestamps (https://connect.withsecure.com/api-reference/elements#get-/devices/v1/devices).

dolatawojciech · March 2023

Elements API

Changes in existing endpoints:

Security events endpoint: engine and severity query parameters support multiple values (https://connect.withsecure.com/api-reference/elements#get-/security-events/v1/security-events).

dolatawojciech · March 2023

Elements API

Changes in existing endpoints:

Devices endpoint: added new filter protectionStatusOverview
(https://connect.withsecure.com/api-reference/elements#get-/devices/v1/devices)

dolatawojciech · March 2023

Elements API

Changes in API Clients UI:

Removed the organization column, current organization still can be seen in top bar.

Milosz · March 2023

Elements API: Listing EDR dections and isolating computer from network

New features are released in Elements API:

Listing detections of EDR incident - client can correlate EDR incident
with list of events from EDR detection engine.
Isolating computer from network and relasing from isolation - client can send
command, that isolates workstation or server at risk. Other supported operation
allows releasing safe computer from isolation.
Support for other remote operations will be extended in the future.
Reading list of remote operations - client can check status of remote operation for
particular computer.

Triggering remote operations is only allowed for clients with Read/Write permissions.
Getting Started guide contains information how to add credentials with required grant.

Milosz · April 2023

Elements API: Managing EPP invitations

Authorized client can manage EPP invitations:

list pending or expired invitations
create new invitation - installation link with one-time password is sent to specified recipient
delete invitation - pending invitation is canceled and can't be used anymore
renew expired invitation or resend pending invitation

Legacy EPP API for managing invitations is deprecated.

SergeH · May 2023

Endpoint Protection API: Provisioning invitations endpoints end of life on 3rd of November 2023

The old invitations endpoints are deprecated and should be replaced by the new Elements devices endpoints: https://connect.withsecure.com/api-reference/elements#tag--invitations

The following Endpoint Protection API invitation endpoints will stop working on the 03.11.2023:

Create new invitation
List pending or expired invitations
Remove invitations
Renew expired invitations
Resend pending invitations

Reminder: In order to provide a better and unified set of APIs for WithSecure Elements, we are progressively deprecating the Endpoint Protection API and replacing it by Elements API. The following endpoints will reach their end of life soon as indicated earlier in this change log

Computers endpoint: 30th of May
Security events endpoint: 30th of June
Companies endpoint: 31st of July

NicoL · May 2023

Provisioning API

· Update Service Partner (SEP) name

This new API call allows to change an existing Service Partner(SEP) name by using the unique identifier as described in https://connect.withsecure.com/api-reference/provisioning#post-/seps/-partner_uuid-

Milosz · May 2023

Elements API: New properties in devices list

New properties has been added to to device list endpoint:

total and free space on system drive
total and free physical memory
Vulnerability Management risk score. That values is calculated only for devices with active VM module
EDR incidents counters
computer model and BIOS version
version of malware database and timestamp of its last update
list of MAC addresses
property that indicates if user has administrator privileges

maciej_antkiewicz · June 2023

Elements API:

Manage devices

New endpoints are published:
- Update device state - client can block or inactivate devices
- Remove devices - client can delete device

List devices endpoint was updated and now devices can be filtered by state. Also, state field is always returned in the response.

List incidents

New endpoint is published:

- List incidents - client can view list of the incidents in the organization

Milosz · July 2023

Elements API: managing status of EDR incident

New endpoint for managing status of EDR incidents is available. Client can update status of incident or close it with specified resolution.

Hubert_Szymanski · August 2023

Elements API: new filters for devices and incidents

Incidents: new filter riskLevel has been introduced to incidents listing endpoint. It may be used to list incidents with higher risk levels.
Devices: new filter subscriptionKey has been introduced to devices listing endpoint. It allows to list only devices from specified subscription key.

Hubert_Szymanski · August 2023

Elements API: cookbook and new filter for incidents

Cookbook: To help our customers integrating with Elements API we created Elements API Cookbook. It contains recipes with descriptions of common use cases and example solutions implemented as Python procedures.
Incidents: new filters updatedTimestampStart & updatedTimestampEnd have been introduced to incidents listing endpoint. Main use case is to enhance incidents and detections polling as filtering by updatedTimestamp helps getting recent updates. Please, learn more from recipe in our new Cookbook - poll detections.
Additionally exclusiveStart flag has been added to help with avoiding duplicates while polling incidents.

NicoL · August 2023

Provisioning API

· Move Company

This new API call allows to move a company to Service Partner (SEP) or Buyer Party, but the changes only allowed within the same Buyer Party of the company as described in https://connect.withsecure.com/api-reference/provisioning#post-/company/-companyUuid-

*The endpoint is only available to selected buyer

Elements API Changelog

Comments

Provisioning API

· New url to reflect our new brand

· Get subscription

Provisioning API

· Register a Service Partner (SEP)

Endpoint Protection API

Poll for security events

Provisioning API

· Get subscriptions by company uuid

· Get subscriptions by reference number

Provisioning API

· Get subscriptions by partner uuid

· Get subscriptions by buyer account id

Provisioning API

New products are now supported in Provisioning API

Provisioning API

· Terminate subscription

Elements API

Elements API

Elements API

Elements API

Elements API

Endpoint Protection API

Endpoint Protection API

Elements API

Provisioning API

Fixed the missing product in Provisioning API Get Subscription endpoints.

Elements API

Elements API

Elements API

Elements API

Elements API: Listing EDR dections and isolating computer from network

Elements API: Managing EPP invitations

Provisioning API

· Update Service Partner (SEP) name

Elements API: New properties in devices list

Elements API: managing status of EDR incident

Elements API: new filters for devices and incidents

Elements API: cookbook and new filter for incidents

Provisioning API

· Move Company

Categories