Reference manual

This is the reference document for the WithSecure Elements VM API. The API targets developers who want to integrate WithSecure Elements VM with third party applications.

This is the API version devoted for developers wanting to integrate with WithSecure Elements VM. It's mostly consistent with the 'latest' version of the API with the exception of breaking changes. In case breaking change on the API endpoint is introduced, the old version is still supported for some time in the 'integration' version of the API. This gives time for third party integration to switch to the new endpoint. The WithSecure Elements VM API is also available as a JSON document that contains the documentation for each resource in the API.

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 a following way:

GET - for reading resources
POST - for creating new resources
PUT - for updating existing resources
DELETE - for removing resources

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 provide two types of API channels (they may be regarded as two API versions serving different purposes):

latest channel: Up to date API development. May introduce breaking changes without prior notice. Click here to see the documentation.
integration channel: Designated for developers wanting to integrate with WithSecure Elements VM. Will preserve existing endpoints for a time being if a breaking change is introduced in the 'latest' channel (users will be notified as of 2018-01-01). Click here to see the documentation.

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 ApiAccessKey) 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:

Log in to WithSecure Elements VM.
Select My profile.
Scroll down to the Configure API Keys section.
Add a new API key and store it safely.
Apply the created API key to the HTTP header of every API request that requires authentication.
Run a simple request to check the authentication:


                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. Enclosing braces must be omitted when you submit requests.

If authentication was successful, you will get a HTTP 'Authenticated' response with status code 200.

Above example as well as all sample requests described in use cases are performed towards the integration channel of the API located on 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 WithSecure Elements VM API help page to see 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 particular client exceeds the limit, 429 HTTP error message (Too Many Requests) is responsed to client. Response contains 'Retry-After' HTTP header that inform how long to wait before request could be resubmitted.

API documentation

Documentation source file here.