We want to inform you about an upcoming breaking change that will impact our service. Please read the following details carefully.
Read more
The WithSecure Elements VM API is intended for developers who want to integrate WithSecure Elements VM with third-party applications.
This documentation gives a quick introduction to the WithSecure Elements VM API and discusses its conventions and best practices.
URI structure
WithSecure Elements VM API provides access to resources (data entities) via URI paths. By default, the WithSecure Elements VM API uses JSON as its communication format and standard HTTP methods like GET, PUT, POST, and DELETE, most often in the following way:
Access to most resources via WithSecure Elements VM API requires user authentication. However there are several API actions that can be performed anonymously.
API channels
WithSecure Elements VM provides two API channels (they may be regarded as two API versions serving different purposes):
Deprecated endpoints
Existing API endpoints are marked as deprecated before they are removed permanently. These deprecated endpoints return the following HTTP header, containing a date of permanent removal (by default, after 30 days):
deprecated: This endpoint is deprecated and will be removed on {date}. Please see the 'latest' channel of the API documentation to find the endpoint replacement.;
Request headers and parameters
To follow best practices and to ensure that all requests work correctly, apply the following HTTP header to all API requests:
Content-Type: application/json;
The request authentication headers (ApiAccessKey and ApiSecretKey) together with their values are case-sensitive.
The parameter names in the request body are also case-sensitive.
Authentication
WithSecure Elements VM API uses API keys for authentication. An API key consists of an access key (for example, PA3IAKNANLM9) and a secret key (for example, UO9mkDEHFGa1Vau6o#1AfxwRmBQW@!qV). To create an API key:
curl -X GET https://api.radar-prd.fsapi.com/api/integration/authenticationcheck
-H 'Content-Type: application/json'
-H 'ApiAccessKey: {ApiAccessKey}'
-H 'ApiSecretKey: {ApiSecretKey}'
Note that access and secret keys in the above request must be replaced with real values. Omit the enclosing brackets when you submit requests.
If authentication was successful, you will get a HTTP 'Authenticated' response with status code 200.
The above example, as well as all sample requests described in use cases, are performed on the integration channel of the API, located at https://api.radar-prd.fsapi.com/. If you are using a different channel or instance of WithSecure Elements VM, replace it with the appropriate server URL.
Use cases
See the WithSecure Elements VM API help page for example use cases.
Throttle API requests for better throughput
WithSecure Elements VM throttles API requests to prevent servers from being overwhelmed by too many requests. When request submissions from a particular client exceeds the limit, a 429 HTTP error message (Too Many Requests) is sent to the client. The response contains a 'Retry-After' HTTP header that indicates how long to wait before resubmitting the request.