API Guide for Data Security for Dell

Introduction

Data Security exposes a REST API, hosted on the Eyeglass appliance, that lets external applications retrieve active threat/security event information and, where licensed, take response actions (critical path snapshots, user lockout/unlock). This is commonly referred to as the Zero Trust API. It is used both for direct integration with third-party security tools (SIEM, SOAR, IDS/IPS) and internally by other Superna products — for example, Data Orchestration (Golden Copy) uses this same token and endpoint to automatically pause backup jobs while an active threat is detected. See Smart AirGap / Ransomware Defender Integration in the Data Orchestration Integration Guide for the Golden Copy side of this configuration.

Requirements

A Zero Trust API license key is required for the critical-path-snapshot and user-lockout/unlock endpoints. Read-only event endpoints do not require the Zero Trust license.

Authentication: Creating an API Token

All API calls are authenticated with a token generated from Eyeglass. Each token identifies the calling application in the Eyeglass logs, which is useful for tracing which integration triggered a given action.

1. Log in to the Eyeglass appliance.
2. Open the Eyeglass REST API menu item (available with Enterprise license keys), or navigate through Eyeglass Menu → Integrations → API Tokens.
3. Click Create New Token and enter a name that identifies the calling application (for example, Golden Copy or SIEM Integration).
4. Copy the generated token. Revoking a token immediately disables that application's access to the API.

Include the token in an HTTP header named api_key on every request:

curl --header "api_key: igls-abc123" --header "accept: application/json" https://<eyeglass-ip>/sera/v1/securityevents

tip

The Eyeglass API Explorer (https://<eyeglass-ip>/sera/docs/) can browse available routes and build a working curl command interactively once a valid token is supplied.

Endpoints

GET /v1/ransomware/rswevents

Returns a list of active Ransomware Defender (RSW) events only.

GET /v1/securityevents

Returns a list of active security events, optionally filtered by type.

Parameter	Values	Description
type	all, rsw, ea	Filter by event type: all events, Ransomware Defender events, or Easy Auditor events.

GET /v2/ransomware/criticalpaths

Returns recent critical-path snapshot jobs, optionally filtered by state.

Parameter	Values	Description
state	all, running, finished	Filter jobs by run state.

POST /v2/ransomware/criticalpaths

Initiates a snapshot job across all configured critical paths. Returns a job id used to poll status.

GET /v2/ransomware/criticalpaths/{id}

Retrieves the status/details of a previously submitted critical-path snapshot job by its job id.

POST /v2/ransomware/lockout/{user}

Creates a ransomware event and locks out the specified user (by SID or username) across configured platforms. Returns a job id.

POST /v2/ransomware/unlock/{user}

Unlocks a previously locked-out user by username. Returns a job id.

All endpoints return a {"code": ..., "message": "..."} error payload on failure.

Critical-Path Snapshot Request Hold-Off Timer

To prevent repeated external triggers (for example, multiple IDS/IPS detections within a short window) from creating excessive snapshots, the Zero Trust API applies a hold-off ("dead") timer to POST /v2/ransomware/criticalpaths requests. By default, only 1 snapshot request per hour is honored per critical path — additional requests within that window are ignored.

This hold-off timer is a separate setting from the Ransomware Defender Snapshot Quota/default snapshot expiry (see Snapshot Settings and the CLI Guide), which controls how long a created snapshot is retained before it is deleted, not how frequently new snapshot requests are honored.

To change the default 1-hour hold-off window:

1. Log in to the Eyeglass VM as admin and elevate with sudo -s.

2. Edit /opt/superna/sca/data/system.xml.

3. Locate the <rsware> tag and add (or edit) the following child tag, replacing X with the desired number of hours:

   <api_request_dead_time_hours>X</api_request_dead_time_hours>

4. Save and exit (Ctrl+X).

Use Cases

• SIEM/SOAR polling — poll /v1/securityevents on a schedule to feed active threat state into an external security dashboard or alerting pipeline.
• Backup/archive gating — an external job (for example, a Data Orchestration/Golden Copy archive or recall job) checks active ransomware/security events before running and defers or blocks the job if a threat is active. The configuration steps used on the Golden Copy side of this integration are documented in the Data Orchestration Integration Guide.
• Custom incident response — trigger a critical-path snapshot or user lockout from a SOAR playbook or custom script in response to an alert raised outside of Data Security. See the Microsoft integration guides for examples of this pattern built on Logic Apps playbooks.

See Also

• Threat Response, Lockout and Snapshots – Threat detection and lockout configuration referenced by the events and lockout endpoints above.
• Integration Guide – Third-party SIEM/SOAR/EDR integrations that build on this API.