Elements API Changelog
This thread is a changelog for the WithSecure Elements API.
📝 Click here to see the most recent change log and bookmark the discussion to be notified of any updates.
Comments
-
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-/partners/-partnerId-/infections
-
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-
- Production:
-
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
-
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
-
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-
-
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-
-
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-
-
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
-
-
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
-
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
-
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.
-
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
-
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).
-
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
-
Elements API
Changes in existing endpoints:
- Devices endpoint: New fields were added to response with device type
computercontaining last software scan and install timestamps (https://connect.withsecure.com/api-reference/elements#get-/devices/v1/devices).
- Devices endpoint: New fields were added to response with device type
-
Elements API
Changes in existing endpoints:
- Security events endpoint:
engineandseverityquery parameters support multiple values (https://connect.withsecure.com/api-reference/elements#get-/security-events/v1/security-events).
- Security events endpoint:
-
Elements API
Changes in existing endpoints:
- Devices endpoint: added new filter
protectionStatusOverview
(https://connect.withsecure.com/api-reference/elements#get-/devices/v1/devices)
- Devices endpoint: added new filter
-
-
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. - Listing detections of EDR incident - client can correlate EDR incident
-
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.
-
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
-
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-
-
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
-
Elements API:
Manage devices
New endpoints are published:
- Update device state - client can block or inactivate devices
- Remove devices - client can delete deviceList 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
-
Elements API: new filters for devices and incidents
- Incidents: new filter
riskLevelhas been introduced to incidents listing endpoint. It may be used to list incidents with higher risk levels. - Devices: new filter
subscriptionKeyhas been introduced to devices listing endpoint. It allows to list only devices from specified subscription key.
- Incidents: new filter
-
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&updatedTimestampEndhave been introduced to incidents listing endpoint. Main use case is to enhance incidents and detections polling as filtering byupdatedTimestamphelps getting recent updates. Please, learn more from recipe in our new Cookbook - poll detections.
AdditionallyexclusiveStartflag has been added to help with avoiding duplicates while polling incidents.
-
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
