--- title: Cyberhaven Connector slug: connectors/cyberhaven-connector docTags: createdAt: 2026-10-12T09:27:29.276Z --- Cyberhaven provides advanced data tracing and DLP capabilities to monitor, analyze, and protect sensitive information across endpoints and users. Cyberhaven is a leading data detection and response (DDR) platform that protects sensitive data from insider threats and data loss by monitoring endpoints, user activity, and incidents in real time. This connector enables Swimlane Turbine users to automate the retrieval, management, and enrichment of Cyberhaven DLP incidents, endpoint compliance status, event details, and insider risk scores—without writing code. By integrating Cyberhaven with Turbine, security teams can streamline incident response, accelerate investigations, and maintain continuous compliance across their environment. The connector empowers users to orchestrate complex workflows, reduce manual effort, and respond faster to data risks and policy violations. ### Limitations `not_seen_for_days` and `unassigned_policy_only` on List Endpoints are applied to the page the API returns. Increase the page size, or page with `page_id`, when you need a wider set. The API status `inactive` selects endpoints that are not reporting, and `general_update_required` selects outdated agents. User risk scores are taken from incident fields `risk_score` and `user_risk_groups` on the incident page you request. ### Supported Versions Cyberhaven public API v2. ## Prerequisites To use the Cyberhaven connector, ensure you have the following prerequisites: - Token authentication using a long-lived refresh token. The connector exchanges this for a short-lived access token and refreshes it automatically. The refresh token is securely stored in the Swimlane vault. - URL: The base URL for your Cyberhaven API instance. - Refresh Token: A long-lived refresh token used to obtain and renew access tokens for API authentication. ## Authentication Methods The connector posts the refresh token to `/public/v2/auth/token/access` and sends the returned bearer token on later calls. Access tokens last about 15 minutes. The connector refreshes the token before it expires and again if Cyberhaven returns HTTP 401. ## Capabilities - List Endpoints - List Incidents - Get Incident - Update Incident - Get Event Details - Get Event Lineage - Get User Risk Scores ### List Endpoints Retrieves endpoint inventory from `POST /public/v2/endpoints/list`. | Use case | Inputs | | ----------------------- | -------------------------------------------------------------- | | Outlook plugin disabled | `statuses`: `win_outlook_plugin_disabled` | | Operating system | `oses`: `windows` | | Endpoint group | `groups`: `Testing` | | Outdated agent | `statuses`: `general_update_required`, or `lightbeam_versions` | | Not seen | `statuses`: `inactive`, or `not_seen_for_days` | | No assigned group | `unassigned_policy_only`: true | ### List Incidents Lists incidents from `POST /public/v2/incidents/list`. Filter with `policy_severities` (`informational`, `low`, `medium`, `high`, `critical`), status, user, assignee, or time range. ### Get Incident Loads one incident by id, including policy, user, risk score, and event details. ### Update Incident Updates an incident with `PATCH /public/v2/incidents/{id}`. Set `status` to `closed` and a `close_reason` to close it. API close reasons are `valid`, `invalid_data_mislabled`, `invalid_destination_not_risk`, `invalid_user_exempt`, and `invalid_other`. ### Get Event Details Loads EventService records from `POST /public/v2/event-details`. ### Get Event Lineage Loads the lineage chain between two events from `POST /public/v2/event-lineage`. ### Get User Risk Scores Lists incidents for the users you name and returns each user's highest `risk_score`, `user_risk_groups`, and incident count. ## Additional Documentation - [Cyberhaven API documentation](https://docs.cyberhaven.io/apidocs) # Configurations ## Cyberhaven API Authentication Token authentication using a long-lived refresh token. The connector exchanges it for a short-lived access token and refreshes that token automatically. The refresh token is stored as a password so Turbine keeps it in the vault. ### Configuration Parameters | **Parameter** | **Description** | **Type** | **Required** | | -------------- | ----------------------------------------------------------------------------------------------------------------------- | -------- | ------------ | | url | Cyberhaven tenant URL, for example [https://example.cyberhaven.io](https://example.cyberhaven.io). | string | Required | | refresh\_token | Long-lived refresh token from the Cyberhaven console (Preferences > API token management). Stored in the Turbine vault. | string | Required | | verify\_ssl | Verify the Cyberhaven server certificate. | boolean | Optional | | http\_proxy | Proxy to route requests through. | string | Optional | # Actions ## Get Event Details Retrieve detailed records for one or more Cyberhaven event IDs by calling the EventService endpoint. ### Endpoint - **URL:** `/public/v2/event-details` - **Method:** `POST` ### Input | **Argument Name** | **Type** | **Required** | **Description** | | ----------------- | -------- | ------------ | ------------------------ | | `event_ids` | array | Optional | Event UUIDs to retrieve. | ### Input Example `{"json_body":{"event_ids":["11111111-2222-3333-4444-555555555555"]}}` ### Output | **Parameter** | **Type** | **Description** | | ----------------------- | -------- | ----------------------------------- | | `status_code` | number | HTTP status code of the response | | `reason` | string | Response reason phrase | | `resources` | array | Output field: resources | | `resources.id` | string | Unique identifier | | `resources.timestamp` | string | Output field: resources.timestamp | | `resources.user` | object | Output field: resources.user | | `resources.action` | object | Output field: resources.action | | `resources.source` | object | Output field: resources.source | | `resources.destination` | object | Output field: resources.destination | ### Output Example `{"resources":[{"id":"12345678-1234-1234-1234-123456789abc","timestamp":"2024-01-01T00:00:00Z","user":{},"action":{},"source":{},"destination":{}}]}` ## Get Event Lineage Retrieve the lineage chain between two Cyberhaven events by specifying start and end event IDs, providing a detailed trace of related activities. ### Endpoint - **URL:** `/public/v2/event-lineage` - **Method:** `POST` ### Input | **Argument Name** | **Type** | **Required** | **Description** | | ----------------- | -------- | ------------ | ------------------------------------- | | `start_event_id` | string | Optional | UUID of the first event in the chain. | | `end_event_id` | string | Optional | UUID of the last event in the chain. | ### Input Example `{"json_body":{"start_event_id":"11111111-2222-3333-4444-555555555555","end_event_id":"66666666-7777-8888-9999-aaaaaaaaaaaa"}}` ### Output | **Parameter** | **Type** | **Description** | | ------------- | -------- | -------------------------------- | | `status_code` | number | HTTP status code of the response | | `reason` | string | Response reason phrase | | `resources` | array | Output field: resources | ### Output Example `{"resources":["string"]}` ## Get Incident Fetch a specific Cyberhaven incident by incident ID, including policy, user, risk score, and event details using the POST /public/v2/incidents/list endpoint. ### Endpoint - **URL:** `/public/v2/incidents/list` - **Method:** `POST` ### Input | **Argument Name** | **Type** | **Required** | **Description** | | ---------------------- | -------- | ------------ | --------------------------------------------------- | | `incident_id` | string | Optional | Cyberhaven incident id. | | `include_ai_summaries` | boolean | Optional | Include the AI-generated summary. Defaults to true. | ### Input Example `{"json_body":{"incident_id":"6f1c0a2e-1b2c-4d5e-8f90-1234567890ab","include_ai_summaries":true}}` ### Output | **Parameter** | **Type** | **Description** | | ---------------------------- | -------- | ------------------------------------------ | | `status_code` | number | HTTP status code of the response | | `reason` | string | Response reason phrase | | `resources` | array | Output field: resources | | `resources.id` | string | Unique identifier | | `resources.status` | string | Status value | | `resources.blocked` | boolean | Output field: resources.blocked | | `resources.trigger_time` | string | Time value | | `resources.event_time` | string | Time value | | `resources.ai_summary` | string | Output field: resources.ai\_summary | | `resources.risk_score` | number | Score value | | `resources.user_risk_groups` | array | Output field: resources.user\_risk\_groups | | `resources.assigned_to` | string | Output field: resources.assigned\_to | | `resources.close_reason` | string | Response reason phrase | | `resources.close_note` | string | Output field: resources.close\_note | | `resources.user` | object | Output field: resources.user | | `resources.policy` | object | Output field: resources.policy | | `resources.dataset` | object | Response data | | `resources.event_details` | object | Output field: resources.event\_details | | `resources.event_lineage_id` | object | Unique identifier | | `page_response` | object | Output field: page\_response | ### Output Example `{"resources":[{"id":"12345678-1234-1234-1234-123456789abc","status":"active","blocked":true,"trigger_time":"string","event_time":"string","ai_summary":"string","risk_score":123,"user_risk_groups":[],"assigned_to":"string","close_reason":"string","close_note":"string","user":{},"policy":{},"dataset":{},"event_details":{}}],"page_response":{}}` ## Get User Risk Scores Retrieve insider-risk scores for users from Cyberhaven incidents, returning each user's highest risk score, associated risk groups, and incident count. ### Endpoint - **URL:** `/public/v2/incidents/list` - **Method:** `POST` ### Input | **Argument Name** | **Type** | **Required** | **Description** | | --------------------- | -------- | ------------ | --------------------------------------------------------------------------------- | | `user` | string | Optional | Email or alias of one user. Combined with users when both are set. | | `users` | array | Optional | Emails or aliases to include. | | `policy_severities` | array | Optional | Only consider incidents at these severities. | | `resolution_statuses` | array | Optional | Only consider incidents in these statuses. | | `start_time` | string | Optional | Include incidents at or after this UTC time, formatted as yyyy-mm-ddTHH\:MM\:SSZ. | | `end_time` | string | Optional | Include incidents before this UTC time, formatted as yyyy-mm-ddTHH\:MM\:SSZ. | | `page_size` | number | Optional | Incidents to read when building scores. The API accepts up to 200. | | `page_id` | string | Optional | page\_response.next\_id from a previous response. | ### Input Example `{"json_body":{"user":"analyst@example.com","policy_severities":["high","critical"],"page_size":100}}` ### Output | **Parameter** | **Type** | **Description** | | ------------------------------- | -------- | ----------------------------------------------------------- | | `status_code` | number | HTTP status code of the response | | `reason` | string | Response reason phrase | | `users` | array | One score row per user found in the incident page. | | `users.id` | string | Unique identifier | | `users.email` | string | Output field: users.email | | `users.local_id` | string | Unique identifier | | `users.risk_score` | number | Highest incident risk score seen for this user on the page. | | `users.user_risk_groups` | array | Output field: users.user\_risk\_groups | | `users.incident_count` | number | Unique identifier | | `users.highest_policy_severity` | string | Output field: users.highest\_policy\_severity | | `resources` | array | Incidents used to build the scores. | | `page_response` | object | Output field: page\_response | ### Output Example `{"users":[{"id":"12345678-1234-1234-1234-123456789abc","email":"user@example.com","local_id":"string","risk_score":123,"user_risk_groups":[],"incident_count":123,"highest_policy_severity":"string"}],"resources":[],"page_response":{}}` ## List Endpoints Retrieve and filter Cyberhaven endpoints based on compliance criteria such as disabled Outlook plugins, operating system, group assignment, agent status, and activity. ### Endpoint - **URL:** `/public/v2/endpoints/list` - **Method:** `POST` ### Input | **Argument Name** | **Type** | **Required** | **Description** | | ------------------------ | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `statuses` | array | Optional | Endpoint statuses to include. Outlook plugin disabled is win\_outlook\_plugin\_disabled. Outdated agents use general\_update\_required. Endpoints that are not reporting use inactive. | | `not_statuses` | array | Optional | Endpoint statuses to exclude. | | `oses` | array | Optional | Operating systems to include, for example windows. | | `os_versions` | array | Optional | Operating system versions to include. | | `groups` | array | Optional | Endpoint group names to include, for example Testing. | | `hostnames` | array | Optional | Hostnames to include. | | `ids` | array | Optional | Endpoint record ids to include. | | `lightbeam_versions` | array | Optional | Sensor versions to include. Use this with general\_update\_required to find outdated agents. | | `status_groups` | array | Optional | Status groups to include. | | `deleted` | boolean | Optional | When true, include deleted endpoints. | | `not_seen_for_days` | number | Optional | Keep endpoints on this page whose last report\_time is older than this many days, or that have no report time. Pair with a large page size. The inactive status filter asks the API for endpoints that are not reporting. | | `unassigned_policy_only` | boolean | Optional | Keep endpoints on this page that have no group id and no group name. | | `page_id` | string | Optional | next\_page\_id from a previous response. Leave empty for the first page. | | `size` | number | Optional | Number of endpoints to request. | | `sort_by` | string | Optional | Column to sort by. | | `sort_ascending` | boolean | Optional | When true, sort ascending. | ### Input Example `{"json_body":{"statuses":["win_outlook_plugin_disabled"],"oses":["windows"],"groups":["Testing"],"size":100}}` ### Output | **Parameter** | **Type** | **Description** | | ---------------------------------------------- | -------- | ------------------------------------------------------------------------------------- | | `status_code` | number | HTTP status code of the response | | `reason` | string | Response reason phrase | | `next_page_id` | string | Unique identifier | | `total_records` | number | Output field: total\_records | | `matched_records` | number | Count after not\_seen\_for\_days or unassigned\_policy\_only is applied to this page. | | `records` | array | Output field: records | | `records.id` | string | Unique identifier | | `records.endpoint_id` | string | Unique identifier | | `records.hostname` | string | Name of the resource | | `records.os` | string | Output field: records.os | | `records.os_version` | string | Output field: records.os\_version | | `records.group_id` | string | Unique identifier | | `records.group_name` | string | Name of the resource | | `records.lightbeam_version` | string | Output field: records.lightbeam\_version | | `records.report_time` | string | Time value | | `records.deleted` | boolean | Output field: records.deleted | | `records.statuses_and_actions` | array | Status value | | `records.statuses_and_actions.status` | string | Status value | | `records.statuses_and_actions.required_action` | string | Status value | ### Output Example `{"next_page_id":"string","total_records":123,"matched_records":123,"records":[{"id":"12345678-1234-1234-1234-123456789abc","endpoint_id":"string","hostname":"Example Name","os":"string","os_version":"string","group_id":"string","group_name":"Example Name","lightbeam_version":"string","report_time":"string","deleted":true,"statuses_and_actions":[]}]}` ## List Incidents Retrieve a list of Cyberhaven DLP incidents with options to filter by policy severity, status, assignee, user, time range, or incident ID. ### Endpoint - **URL:** `/public/v2/incidents/list` - **Method:** `POST` ### Input | **Argument Name** | **Type** | **Required** | **Description** | | ---------------------- | -------- | ------------ | --------------------------------------------------------------------------------- | | `policy_severities` | array | Optional | Policy severities to include. | | `resolution_statuses` | array | Optional | Incident statuses to include. | | `assignees` | array | Optional | Analyst emails assigned to the incident. | | `users` | array | Optional | Emails or aliases of users who triggered the incident. | | `incident_ids` | array | Optional | Incident ids to include. | | `start_time` | string | Optional | Include incidents at or after this UTC time, formatted as yyyy-mm-ddTHH\:MM\:SSZ. | | `end_time` | string | Optional | Include incidents before this UTC time, formatted as yyyy-mm-ddTHH\:MM\:SSZ. | | `include_ai_summaries` | boolean | Optional | Include AI-generated incident summaries. Defaults to true. | | `page_size` | number | Optional | Incidents per page. The API defaults to 25 and accepts up to 200. | | `page_id` | string | Optional | page\_response.next\_id from a previous response. Leave empty for the first page. | | `sort_by` | string | Optional | Field to sort by. Defaults to trigger\_time. | ### Input Example `{"json_body":{"policy_severities":["high","critical"],"resolution_statuses":["open"],"page_size":25,"sort_by":"trigger_time"}}` ### Output | **Parameter** | **Type** | **Description** | | ---------------------------- | -------- | ------------------------------------------ | | `status_code` | number | HTTP status code of the response | | `reason` | string | Response reason phrase | | `resources` | array | Output field: resources | | `resources.id` | string | Unique identifier | | `resources.status` | string | Status value | | `resources.blocked` | boolean | Output field: resources.blocked | | `resources.trigger_time` | string | Time value | | `resources.event_time` | string | Time value | | `resources.reaction_time` | string | Time value | | `resources.ai_summary` | string | Output field: resources.ai\_summary | | `resources.ai_severity` | string | Output field: resources.ai\_severity | | `resources.risk_score` | number | Score value | | `resources.user_risk_groups` | array | Output field: resources.user\_risk\_groups | | `resources.created_by` | string | Output field: resources.created\_by | | `resources.assigned_to` | string | Output field: resources.assigned\_to | | `resources.close_reason` | string | Response reason phrase | | `resources.close_note` | string | Output field: resources.close\_note | | `resources.warning_status` | string | Status value | | `resources.user` | object | Output field: resources.user | | `resources.user.id` | string | Unique identifier | | `resources.user.local_id` | string | Unique identifier | | `resources.user.email` | string | Output field: resources.user.email | | `resources.policy` | object | Output field: resources.policy | | `resources.policy.id` | string | Unique identifier | | `resources.policy.name` | string | Name of the resource | ### Output Example `{"resources":[{"id":"12345678-1234-1234-1234-123456789abc","status":"active","blocked":true,"trigger_time":"string","event_time":"string","reaction_time":"string","ai_summary":"string","ai_severity":"string","risk_score":123,"user_risk_groups":[],"created_by":"string","assigned_to":"string","close_reason":"string","close_note":"string","warning_status":"active"}],"page_response":{"next_id":"string","total":123}}` ## Update Incident Update or close a Cyberhaven incident by setting its status and providing a close reason such as valid, invalid\_data\_mislabled, invalid\_destination\_not\_risk, invalid\_user\_exempt, or invalid\_other. ### Endpoint - **URL:** `/public/v2/incidents/{{incident_id}}` - **Method:** `PATCH` ### Input | **Argument Name** | **Type** | **Required** | **Description** | | ----------------------------- | -------- | ------------ | ------------------------------------------ | | `path_parameters.incident_id` | string | Required | Cyberhaven incident id to update. | | `status` | string | Optional | New incident status. | | `close_reason` | string | Optional | Reason recorded when closing the incident. | | `close_note` | string | Optional | Free-text note stored with the closure. | | `assigned_to` | string | Optional | Email of the analyst to assign. | ### Input Example `{"json_body":{"status":"closed","close_reason":"valid","close_note":"User confirmed the transfer was approved."},"path_parameters":{"incident_id":"6f1c0a2e-1b2c-4d5e-8f90-1234567890ab"}}` ### Output | **Parameter** | **Type** | **Description** | | ------------------------ | -------- | ------------------------------------ | | `status_code` | number | HTTP status code of the response | | `reason` | string | Response reason phrase | | `resources` | array | Output field: resources | | `resources.id` | string | Unique identifier | | `resources.status` | string | Status value | | `resources.assigned_to` | string | Output field: resources.assigned\_to | | `resources.close_reason` | string | Response reason phrase | | `resources.close_note` | string | Output field: resources.close\_note | ### Output Example `{"resources":[{"id":"12345678-1234-1234-1234-123456789abc","status":"active","assigned_to":"string","close_reason":"string","close_note":"string"}]}` # Response Headers | **Header** | **Description** | **Example** | | ------------ | ----------------------------------------------------- | ----------------------------- | | Content-Type | The media type of the resource | application/json | | Date | The date and time at which the message was originated | Thu, 01 Jan 2024 00:00:00 GMT |