Community User Guides Support Change Log
Home Getting started API Reference

Elements API getting started

WithSecure Elements API provides an interface to access the WithSecure products through the REST API endpoints. The supported endpoints can be used by partners, resellers, or organizations. You can find a list of currently supported endpoints on the API specification page. The existing API is gradually extended with new products and resources.

The introduction covers the following topics:

  1. Getting client credentials
  2. Client authentication
  3. Making requests
  4. Monitoring device status
  5. Retrieving security events
  6. Rate limiting
  7. Troubleshooting
  8. API deprecation policy

Getting client credentials

To use Elements API, you need client credentials. As an EPP administrator with security management rights and permission to edit computer and server settings, you can create client credentials in Elements Security Center.

You cannot, however, edit existing clients. If you need a client with different permissions, you must remove unused clients and generate a new pair of credentials with a relevant access scope.

To create Elements API credentials

  1. Log in as an EPP administrator in Elements Security Center.

  2. Under Management, select Organization Settings.

  3. In the Organization Settings view, from the menu located at the top select API clients.

  4. From the scope selector, change your scope to the organization for which you want to create a new pair of credentials. Note: If you are a partner and you want to create credentials for an organization, you have to change scope to the organization for which you are issuing the credentials.

    API Keys View

  5. Select Add new.

  6. In the Add new API client window, do the following:

    1. Enter a description for the new client credentials.
    2. Select “Read-only” to allow the client only to read the data. Note: If you want the client to send requests to edit data on the server, for example to trigger new remote operations, clear the checkbox next to “Read-only”. Then, the client can request authentication tokens within the scope connect.api.write.
    3. Select Add.

    Add New API Client

  7. Follow the instructions on the screen. Important: Remember to save the secret value in a safe place, because you are not be able to read the value again.

  8. Select the “I have copied and stored the secret” option, and then select Done.

    Copy Keys

  9. The new item is added to the list.

    Keys List

To delete Elements API credentials

As an EPP administrator, you can remove existing client credentials at any time. Removing credentials breaks any integration that is using removed secrets. Removed credentials cannot be restored.

  1. Log in as an EPP administrator in Elements Security Center.

  2. Under Management, select API client.

  3. From the scope selector, change your scope to the organization whose credentials you want to remove.

  4. In the list, find the credentials that you want to remove and select the trash bin icon in the last column.

  5. Select Delete to confirm the operation.

    Delete Key

Client authentication

Before sending any requests to Elements API, a client must authenticate itself and fetch a security token. Elements API provides an authentication endpoint /as/token.oauth2 which the client uses to obtain a token. Credentials are sent in the “Authorization” header encoded with Base64 in POST request.

The body should be form data with properties: grant_type equal client_credentials and scope that contain the requested access scope:

  • If a client is supposed to change the state of EDR incidents or devices, trigger remote operations, or modify data in any other way, add the following scope: connect.api.write.
  • If a client sends requests to only read data from the server, for example, to read EDR detections, add the following scope: connect.api.read.

You must set a User-agent header. Otherwise, a request is rejected.

Raw request

# HTTP request
POST /as/token.oauth2 HTTP/1.1
Host: api.connect.withsecure.com
user-agent: command-line
content-type: application/x-www-form-urlencoded
Authorization: Basic <credentials_base_64>
grant_type=client_credentials
scope=connect.api.read

Javascript client

// Request from JavaScript client
const client = '...' // client id;
const secret = '...' // secret value
const basic = btoa(`${client}:${secret}`);
const opts = {
  headers: {
    'Authorization': `Basic ${basic}`,
    'user-agent': 'NodeJs',
    'Content-type': 'application/x-www-form-urlencoded'
  },
  method: 'POST'
};
const url = 'https://api.connect.withsecure.com/as/token.oauth2'
const req = https.request(url, opts, (r) => {
  let raw = '';
  r.on('data', (d) =>  { raw += d; });
  r.on('end', () => { console.log(raw); });
});
req.write('grant_type=client_credentials');
req.write('scope=connect.api.read');
req.end();

If the request and credentials are valid, the authentication endpoint answers with an access token

// Response from request
{"access_token":"FdZTq11111116v67lSOx7vyFM2ssnIha","token_type":"Bearer","expires_in":1797}

Making request

Every request that is sent to Elements API must include an access token that is received from an authentication endpoint. The token must be sent in the Authorization header with a Bearer schema. If a request is successful, Elements API answers with HTTP status 200 (OK) and result data in response body. Otherwise, the client receives response with one of the following error status codes: 4xx or 5xx. Each response includes an x-transaction header that the customer support can use for investigation.

Raw request

# HTTP request
GET /whoami/v1/whoami HTTP/1.1
Host: api.connect.withsecure.com
user-agent: command-line
content-type: x-www-form-urlencoded
Authorization: Bearer <access_token>

Javascript client

// Request from JavaScript client
const token = '...'; // access token
const opts = {
  headers: {
    'Authorization': `Bearer ${token}`,
    'user-agent': 'NodeJs'
  },
  method: 'GET'
};
const url = 'https://api.connect.withsecure.com/whoami/v1/whoami'
const req = https.request(url, opts, (r) => {
  let raw = '';
  r.on('data', (d) =>  { raw += d; });
  r.on('end', () => { console.log(raw); });
});
req.end();

// Response from request
{"clientId":"fusion_aae404cb18404fabcede", organizationId":"99999f73-1ee1-414f-b7bb-10a53242759e"}

Timestamps format

Elements API endpoints accept timestamps in a format that matches the RFC 3339 specification:

  • timestamp in the UTC time zone: 2022-11-05T15:08:59Z
  • timestamp in a time zone with an offset from UTC of -08:00: 2022-11-05T07:08:59-08:00
  • timestamp in a time zone with an offset from UTC of +02:00: 2022-11-05T07:17:59+02:00

If an endpoint returns a collection, the items are split, showing up to 200 elements on each page. A client can iterate through a collection using a value from the nextAnchor property that is included in the response on each page.

// Response from request
{
  items: [
    {
      "id": "66787bfd-3fec-4355-955b-790b53ee0199",
      "name": "Example company 1"
    },
    {
      "id": "6827ac27-67b3-45c5-bdd3-69660e8272a8",
      "name": "Example company 2"
    },
    {
      "id": "30ec2ab5-7d4b-458c-bd66-ed099fe42398",
      "name": "Example company 3"
    }
  }],
  "nextAnchor": "anchor-to-next-page"
}

# Next page: HTTP request
GET /organizations/v1/organizations?anchor=anchor-to-next-page&limit=10 HTTP/1.1
Host: api.connect.withsecure.com
user-agent: command-line
content-type: x-www-form-urlencoded
Authorization: Bearer <access_token>

// Next page: JavaScript client
const token = '...'; // access token
const opts = {
  headers: {
    'Authorization': `Bearer ${token}`,
    'user-agent': 'NodeJs'
  },
  method: 'GET'
};
const query = 'anchor=anchor-to-next-page&limit=10' // limit defines page max size
const url = `https://api.connect.withsecure.com/organizations/v1/organizations?${query}`
const req = https.request(url, opts, (r) => {
  let raw = '';
  r.on('data', (d) =>  { raw += d; });
  r.on('end', () => { console.log(raw); });
});
req.end();

Monitoring status of devices

A client can monitor the status of any device that belongs to its organization’s scope. If a client is using credentials that are created on a partner level, it has access to any device that belongs to the child organization.

Listing devices with critical protection status

In the example, a client is authenticated with client credentials that are created on a partner level. A request URL contains the organizationId parameter with a company identifier. Because the second parameter, protectionStatusOverview is equal to critical, the response includes only devices with Critical protection status.

# HTTP request
GET /devices/v1/devices?organizationId=e4bd56b0-90b4-4878-962f-903ea862a977&protectionStatusOverview=critical HTTP/1.1
Host: api.connect.withsecure.com
user-agent: command-line
content-type: x-www-form-urlencoded
Authorization: Bearer <access_token>

// Request from JavaScript client
const token = '...'; // access token
const opts = {
  headers: {
    'Authorization': `Bearer ${token}`,
    'user-agent': 'NodeJs'
  },
  method: 'GET'
};
const query = 'organizationId=e4bd56b0-90b4-4878-962f-903ea862a977&protectionStatusOverview=critical'
const url = `https://api.connect.withsecure.com/devices/v1/devices?${query}`
const req = https.request(url, opts, (r) => {
  let raw = '';
  r.on('data', (d) =>  { raw += d; });
  r.on('end', () => { console.log(raw); });
});
req.end();

Listing devices that are missing critical updates

In the example, a client is authenticated with client credentials that are created on an organization level. A patchOverallState parameter is used to query devices that are missing critical updates.

# HTTP request
GET /devices/v1/devices?patchOverallState=missingCriticalUpdates HTTP/1.1
Host: api.connect.withsecure.com
user-agent: command-line
content-type: x-www-form-urlencoded
Authorization: Bearer <access_token>

// Request from JavaScript client
const token = '...'; // access token
const opts = {
  headers: {
    'Authorization': `Bearer ${token}`,
    'user-agent': 'NodeJs'
  },
  method: 'GET'
};
const query = 'patchOverallState=missingCriticalUpdates'
const url = `https://api.connect.withsecure.com/devices/v1/devices?${query}`
const req = https.request(url, opts, (r) => {
  let raw = '';
  r.on('data', (d) =>  { raw += d; });
  r.on('end', () => { console.log(raw); });
});
req.end();

Retrieving security events

You can retrieve security events for any organization that is in the scope of Elements API client credentials. If credentials are created on a partner level, a client can read security events of organizations that belong to the partner account.

When a client tries to retrieve security events, it must specify one of the following time ranges:

  • start time with the following request parameter to read all events that persisted after the specified date: persistenceTimestampStart
  • end time with the following request parameter to read all events that persisted before the specified date: persistenceTimestampEnd
  • start and end time with the following request parameters to read all events that persisted between the specified dates: persistenceTimestampStart and persistenceTimestampEnd

If a client does not specify any time range parameters, the request fails.

Reading all events in the partner scope

In the example, a client is authenticated with client credentials that are created on a partner level. An organizationId parameter is not specified in the request URL, so Elements API returns events from all organizations that belong to the partner’s organization and that were created before 2023-05-01.

# HTTP request
POST /security-events/v1/security-events HTTP/1.1
Host: api.connect.withsecure.com
user-agent: command-line
content-type: application/x-www-form-urlencoded
Authorization: Bearer <access_token>
persistenceTimestampEnd=2023-05-01T00:00:00Z&engineGroup=epp

// Request from JavaScript client
const token = '...'; // access token
const opts = {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-type': 'application/x-www-form-urlencoded',
    'user-agent': 'NodeJs'
    
  },
  method: 'POST'
};
const form = 'persistenceTimestampEnd=2023-05-01T00:00:00Z&engineGroup=epp'
const url = `https://api.connect.withsecure.com/security-events/v1/security-events`
const req = https.request(url, opts, (r) => {
  let raw = '';
  r.on('data', (d) =>  { raw += d; });
  r.on('end', () => { console.log(raw); });
});
req.write(form);
req.end();

Reading all events from an organization

In the example, a client is authenticated with client credentials that are created on a partner level. An organizationId parameter is present in the request URL, so Elements API returns events that were created after 2023-05-01 for the organization with the given identifier.

# HTTP request
POST /security-events/v1/security-events HTTP/1.1
Host: api.connect.withsecure.com
user-agent: command-line
content-type: application/x-www-form-urlencoded
Authorization: Bearer <access_token>
organizationId=e4bd56b0-90b4-4878-962f-903ea862a977&persistenceTimestampStart=2023-05-01T00:00:00Z&engineGroup=epp

// Request from JavaScript client
const token = '...'; // access token
const opts = {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-type': 'application/x-www-form-urlencoded',
    'user-agent': 'NodeJs'
  },
  method: 'POST'
};
const form = 'organizationId=e4bd56b0-90b4-4878-962f-903ea862a977&persistenceTimestampStart=2023-05-01T00:00:00Z&engineGroup=epp'
const url = `https://api.connect.withsecure.com/security-events/v1/security-events`
const req = https.request(url, opts, (r) => {
  let raw = '';
  r.on('data', (d) =>  { raw += d; });
  r.on('end', () => { console.log(raw); });
});
req.write(form);
req.end();

Rate limiting

Elements API uses rate limiting to protect the system from overload.

The general rate limit is set to 10,000 requests per minute per unique IP address. For EDR endpoints, the rate limit is 300 requests per minute per unique IP address. This applies to:

Troubleshooting

Sometimes request cannot be completed due to errors on a client or server side:

  • When a client sends wrong parameters in its request
  • When requested resources do not exist
  • When a client does not have access to the requested resources
  • When a request to an internal backend fails

In such cases, a response includes error details and a numeric error code. Error codes are described in the API specification page. If a request cannot be completed due to a client error, checking the error details might help in fixing the issue.

Example Error Response

API deprecation policy

As our system evolves and we introduce new functionalities, we may face the need to terminate some existing functionalities in the APIs. In such cases, we will mark the functionality as deprecated in the documentation. We will also announce the change in the Elements API change log.

Next Steps

  1. Review the API Reference for detailed endpoint documentation
  2. Check out the Cookbook for practical examples
  3. Join the Community for support and updates