Google SecOps Cases Integration Guide

Overview

The Google SecOps Cases integration allows your NINA workflows to connect with Google Security Operations (Google SecOps) to manage the full SOC case lifecycle — from creating and triaging cases, to investigating alerts, tracking tasks, managing SLA timers, and annotating evidence with context properties and custom fields. This integration targets the Google SecOps Cases API and provides complete programmatic access to the case management layer of a Google SecOps instance.

Capabilities

This integration provides access to 19 resources with 123 operations covering:

Case Management: List, get, update, merge, close, reopen, and tag cases
Alert Management: List, get, update, and move alerts within cases; manage SLA timers per alert
AI Features: Fetch AI-generated recommendations per alert, generate case summaries, create insights
Collaboration: Send and manage chat messages, pin/unpin messages, download attachments
Activity Timeline: Access and favourite case wall records
Task Tracking: Create, update, complete, and delete case tasks
Evidence & Context: Create and manage context properties and custom field values on cases and alerts
Entity Investigation: Add involved entities to alerts, fetch enrichment cards, manage entity properties
Case Configuration: Manage close definitions, stage definitions, tag definitions, queue filters, SLA definitions
Custom Fields: Define and manage custom field schemas for cases and alerts
Connector Events: Access raw and formatted connector event data tied to alerts

API Versions

The connector targets the most stable version available per operation:

API Version	Usage
`v1`	Core case operations, alerts, comments, wall records, chat, context properties, SLA definitions, tasks, close/stage/tag/queue definitions
`v1alpha`	AI case summaries, custom field values, custom field definitions, case evidence data, alert tag management, alert view listing, connector events

Note: The Google SecOps API exposes the same logical operations across v1, v1alpha, and v1beta. The connector uses v1 where stable and v1alpha for features not yet promoted. The same service account credentials work across all versions.

Credential Configuration

Authentication Method

Google SecOps Cases uses Google Service Account (OAuth2 service-account flow). The integration authenticates by exchanging a service account JSON key for a short-lived Google access token, which is refreshed automatically.

Field	Description	Required
`serviceAccountJson`	Full content of the Google service account JSON key file (paste the entire JSON)	Yes
`region`	Google SecOps API region prefix — must match your Google SecOps instance deployment (e.g. `us`, `eu`)	Yes
`project`	GCP project ID or project number that owns the Google SecOps instance	Yes
`location`	GCP location string for the instance resource path (e.g. `us`, `eu`, `europe-west2`)	Yes
`instance`	Google SecOps instance UUID	Yes

How Authentication Works

You provide the service account JSON key when creating a credential in NINA.
On each API call the connector exchanges the private key from the JSON for a short-lived Google OAuth2 access token using the scope https://www.googleapis.com/auth/cloud-platform.
The token is sent as a Bearer header on every Google SecOps API request.
Google access tokens expire after 1 hour. The golang.org/x/oauth2/google library renews the token automatically — no user interaction is required.
No redirect URLs, browser flows, or user-level OAuth consent screens are involved.

Google SecOps API Regions

Select the region value that matches where your Google SecOps instance is deployed:

`region` value	Label	Google SecOps API base URL
`us`	United States	`https://us-chronicle.googleapis.com`
`eu`	Europe	`https://eu-chronicle.googleapis.com`
`asia-southeast1`	Asia Pacific — Singapore	`https://asia-southeast1-chronicle.googleapis.com`
`australia-southeast1`	Australia — Sydney	`https://australia-southeast1-chronicle.googleapis.com`
`northamerica-northeast2`	Canada — Montreal	`https://northamerica-northeast2-chronicle.googleapis.com`
`me-central1`	Middle East — Qatar	`https://me-central1-chronicle.googleapis.com`

region vs location: The region field determines which Google SecOps API hostname is used (https://{region}-chronicle.googleapis.com). The location field is inserted into the resource path (/v1/projects/{project}/locations/{location}/instances/{instance}). For most deployments these have the same value (e.g. both eu), but some require a full GCP location name (e.g. europe-west2). Confirm the exact location value with your Google SecOps administrator or by inspecting the instance resource name in the Google SecOps UI under Settings → Instance.

How to Obtain a Service Account Key

Step 1 — Identify or create the service account

Go to Google Cloud Console and select the GCP project that owns the Google SecOps instance.
Navigate to IAM & Admin > Service Accounts.
Either select an existing service account dedicated to automation, or click Create Service Account:
- Name: Use a descriptive name (e.g. nina-chronicle-cases).
- Description: e.g. "Service account for NINA Google SecOps Cases connector".
Click Create and Continue.

Step 2 — Grant the required IAM role

Google SecOps uses Google Cloud IAM roles to control access. The minimum roles required are:

Use case	Required IAM role
Read-only (list/get cases, alerts, comments, tasks, definitions)	`roles/chronicle.viewer`
Read + write (update cases, manage tags, manage SLA, create comments/tasks)	`roles/chronicle.editor`
Full access including destructive operations (bulk close, delete tag definitions, clear context properties)	`roles/chronicle.editor`

Important: Google SecOps IAM roles are granted at the GCP project level. Granting roles/chronicle.editor gives the service account editor access to all Google SecOps resources in that project, including the chronicle-instances connector. Apply the principle of least privilege: use roles/chronicle.viewer for monitoring and read-only automation workflows, and roles/chronicle.editor only when write access is required.

To grant the role:

In IAM & Admin > IAM, click Grant Access.
Enter the service account email address (e.g. [email protected]).
Select the appropriate Google SecOps role from the role picker.
Click Save.

Google SecOps-specific IAM roles and their fine-grained permissions are documented at: https://cloud.google.com/iam/docs/understanding-roles#chronicle-roles

Step 3 — Create a JSON key

Go to IAM & Admin > Service Accounts and click the service account you configured.
Open the Keys tab.
Click Add Key > Create new key.
Select JSON format and click Create.
The key file downloads automatically to your computer.
Store the key file securely. Anyone who possesses this file can authenticate as the service account. Do not commit it to source control or log its contents.

The JSON key file has the following structure:

{
  "type": "service_account",
  "project_id": "your-gcp-project-id",
  "private_key_id": "abc123...",
  "private_key": "<the full private key from your key file, including its BEGIN/END PRIVATE KEY lines>",
  "client_email": "[email protected]",
  "client_id": "123456789",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/nina-chronicle-cases%40your-project.iam.gserviceaccount.com"
}

Paste the entire content of this file into the serviceAccountJson credential field in NINA.

Step 4 — Locate your Google SecOps instance details

You need the project, location, and instance values to complete the credential. All three appear in the Google SecOps instance resource name, which follows the pattern:

projects/{project}/locations/{location}/instances/{instance}

To find these values:

project: The GCP project ID shown in the Google Cloud Console project picker (e.g. my-company-chronicle-prod).
location: Visible in the Google SecOps UI under Settings → Instance or by running gcloud chronicle instances list --project=PROJECT_ID. Common values: us, eu, europe-west2.
instance: The UUID shown in the Google SecOps UI under Settings → Instance (e.g. fca7f167-b9d1-43b1-9d03-0257d31dcb63).

Creating a Google SecOps Cases Credential in NINA

Navigate to the Credentials section in NINA.
Click Add New Credential.
Select Google SecOps Cases as the integration service.
Fill in the fields:
- serviceAccountJson: Paste the full content of the JSON key file.
- region: Select the region that matches your Google SecOps deployment (default: us).
- project: Enter your GCP project ID.
- location: Enter the GCP location (e.g. eu).
- instance: Enter the Google SecOps instance UUID.
Click Test Connection to verify the credentials work.
Click Save to store the credential securely.

Shared credentials with Google SecOps Instances: The chronicle-cases and chronicle-instances connectors use identical credential fields and the same service account. If you already have a working credential for chronicle-instances, the same service account JSON, region, project, location, and instance values can be reused for chronicle-cases — you only need to create a second credential record pointing to the same service account.

Rate Limits and Quotas

The Google SecOps API enforces per-project quotas. Google SecOps Cases operations share the same quota pool as Google SecOps Instances operations under the same GCP project.

Behaviour	Detail
Rate limit response	HTTP `429 Too Many Requests`
Retry strategy	The connector retries automatically up to 3 times with exponential back-off (1 s, 2 s, 4 s)
`Retry-After` header	Honoured when present in the 429 response
Timeout	90-second per-request timeout; retried on timeout up to 3 times

For current quota values and increase requests, refer to the Google Cloud Console under APIs & Services → Google SecOps API → Quotas.

Supported Operations

Resources overview

Resource	Description	# Operations
cases	Core SOC case management	20
caseAlerts	Alerts within cases	14
connectorEvents	Raw connector events for alerts	3
alertContextProperties	Key-value context on alerts	6
alertCustomFieldValues	Custom field values on alerts	4
involvedEntities	Entities involved in alerts	7
caseComments	Case comments	5
caseEvidenceData	Evidence data records	2
caseWallRecords	Case activity timeline	4
chatMessages	Real-time case chat	8
caseContextProperties	Key-value context on cases	6
caseCustomFieldValues	Custom field values on cases	4
customFields	Custom field schema definitions	5
caseCloseDefinitions	Close reason definitions	5
caseQueueFilters	Saved case queue filters	7
caseStageDefinitions	Workflow stage definitions	5
caseTagDefinitions	Tag taxonomy definitions	6
slaDefinitions	SLA timer definitions	7
tasks	Case tasks / action items	5

Operation Details

cases

Core case management resource. All case IDs are passed as the caseId parameter.

getCase

Retrieve a single case by its ID.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/cases
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID to retrieve.

Example:

{
  "caseId": "12345"
}

listCases

List cases for the instance with optional filter and ordering.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/cases
API Version: v1

Parameter	Type	Required	Description
`pageSize`	number	No	Maximum number of cases to return.
`pageToken`	string	No	Pagination token from a previous response.
`filter`	string	No	Filter expression (e.g. `status = "OPEN"`).
`orderBy`	string	No	Sort order (e.g. `createTime desc`).

Example:

{
  "pageSize": 25,
  "filter": "status = \"OPEN\"",
  "orderBy": "createTime desc"
}

updateCase

Update one or more fields of an existing case.

HTTP: PATCH /v1/projects/{project}/locations/{location}/instances/{instance}/cases
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID to update.
`updateMask`	string	No	Comma-separated list of field paths to update (e.g. `priority,assignee`). If omitted, all provided fields are updated.
`priority`	string	No	New priority (e.g. `HIGH`, `MEDIUM`, `LOW`).
`assignee`	object	No	Assignee object (`{"user": {"email": "[email protected]"}}`).
`stageId`	string	No	Target stage definition ID.

Example:

{
  "caseId": "12345",
  "updateMask": "priority,assignee",
  "priority": "HIGH",
  "assignee": { "user": { "email": "[email protected]" } }
}

addTag

Add a tag to an existing case.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases:addTag
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`tag`	string	Yes	Tag value to add (must exist as a `caseTagDefinition`).

Example:

{
  "caseId": "12345",
  "tag": "malware"
}

removeTag

Remove a tag from an existing case.

HTTP: DELETE /v1/projects/{project}/locations/{location}/instances/{instance}/cases:removeTag
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`tag`	string	Yes	Tag value to remove.

Example:

{
  "caseId": "12345",
  "tag": "malware"
}

createInsight

Trigger creation of an AI-generated insight for a case.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases:createInsight
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID to create an insight for.

Example:

{
  "caseId": "12345"
}

executeBulkAddTag

Add a single tag to multiple cases in one call.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases:executeBulkAddTag
API Version: v1

Parameter	Type	Required	Description
`caseIds`	array	Yes	List of case IDs to tag (e.g. `["123", "456"]`).
`tag`	string	Yes	Tag value to add.

Example:

{
  "caseIds": ["12345", "12346", "12347"],
  "tag": "ransomware"
}

executeBulkAssign

Assign multiple cases to a user in one call.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases:executeBulkAssign
API Version: v1

Parameter	Type	Required	Description
`caseIds`	array	Yes	List of case IDs to assign.
`assignee`	object	Yes	Assignee object (e.g. `{"user": {"email": "[email protected]"}}`).

Example:

{
  "caseIds": ["12345", "12346"],
  "assignee": { "user": { "email": "[email protected]" } }
}

executeBulkChangePriority

Change the priority of multiple cases at once.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases:executeBulkChangePriority
API Version: v1

Parameter	Type	Required	Description
`caseIds`	array	Yes	List of case IDs.
`priority`	string	Yes	New priority value (e.g. `HIGH`, `MEDIUM`, `LOW`, `CRITICAL`).

Example:

{
  "caseIds": ["12345", "12346"],
  "priority": "CRITICAL"
}

executeBulkChangeStage

Move multiple cases to a specific workflow stage.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases:executeBulkChangeStage
API Version: v1

Parameter	Type	Required	Description
`caseIds`	array	Yes	List of case IDs.
`stageId`	string	Yes	Target stage definition ID. Use `listCaseStageDefinitions` to get valid IDs.

Example:

{
  "caseIds": ["12345"],
  "stageId": "stage-uuid-here"
}

executeBulkClose

Close multiple cases at once.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases:executeBulkClose
API Version: v1

Parameter	Type	Required	Description
`caseIds`	array	Yes	List of case IDs to close.
`closeDefinitionId`	string	No	ID of the close definition (reason) to apply. Use `listCaseCloseDefinitions` to get valid IDs.
`reason`	string	No	Free-text reason for closing.

Warning: This is a destructive operation. Closed cases may not be fully reversible depending on instance configuration.

Example:

{
  "caseIds": ["12345", "12346"],
  "closeDefinitionId": "close-def-uuid",
  "reason": "Resolved as false positive"
}

executeBulkReopen

Reopen multiple previously closed cases.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases:executeBulkReopen
API Version: v1

Parameter	Type	Required	Description
`caseIds`	array	Yes	List of case IDs to reopen.

Example:

{
  "caseIds": ["12345", "12346"]
}

generateReport

Generate a report document for a case.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases:generateReport
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID to generate a report for.

Example:

{
  "caseId": "12345"
}

getCaseOverviewData

Get the overview widget data (summary statistics and charts) for a case.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/cases:getCaseOverviewData
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.

Example:

{
  "caseId": "12345"
}

merge

Merge multiple cases into a single case.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases:merge
API Version: v1

Parameter	Type	Required	Description
`caseIds`	array	Yes	List of case IDs to merge. All cases are merged into `targetCaseId`.
`targetCaseId`	string	No	The case ID that survives the merge. If omitted, the API selects the target automatically.

Warning: This is a destructive operation. Merged cases are closed and their alerts are moved to the target case.

Example:

{
  "caseIds": ["12345", "12346"],
  "targetCaseId": "12345"
}

pauseSla

Pause the SLA countdown timer on a case.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases:pauseSla
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`reason`	string	No	Reason for pausing the SLA (free text).

Example:

{
  "caseId": "12345",
  "reason": "Waiting for customer confirmation"
}

resumeSla

Resume a previously paused SLA timer on a case.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases:resumeSla
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.

Example:

{
  "caseId": "12345"
}

resolveOverviewWidget

Resolve (dismiss) a specific overview widget on a case dashboard.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases:resolveOverviewWidget
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`widgetId`	string	No	The widget ID to resolve.

Example:

{
  "caseId": "12345",
  "widgetId": "widget-abc"
}

countPriorities

Count open cases grouped by priority level.

HTTP: POST /v1alpha/projects/{project}/locations/{location}/instances/{instance}/cases:countPriorities
API Version: v1alpha

Parameter	Type	Required	Description
`filter`	string	No	Optional filter expression to scope which cases are counted (e.g. `status = "OPEN"`).

Example:

{
  "filter": "status = \"OPEN\""
}

getOrCreateCaseSummary

Fetch an existing AI-generated case summary, or trigger generation if one does not exist yet.

HTTP: GET /v1alpha/projects/{project}/locations/{location}/instances/{instance}/cases:getOrCreateCaseSummary
API Version: v1alpha

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.

Note: AI case summaries are a Google SecOps AI feature. They may not be available on all instances. If the feature is not enabled, the API returns FAILED_PRECONDITION.

Example:

{
  "caseId": "12345"
}

caseAlerts

Alerts are the primary unit of investigation within a case. Each alert is identified by a caseId + alertId pair.

getCaseAlert

Retrieve a specific alert from a case.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001"
}

listCaseAlerts

List all alerts associated with a case.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`pageSize`	number	No	Maximum number of alerts to return.
`pageToken`	string	No	Pagination token from a previous response.

Example:

{
  "caseId": "12345",
  "pageSize": 50
}

updateCaseAlert

Update fields of an alert within a case (e.g. analyst feedback).

HTTP: PATCH /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.
`updateMask`	string	No	Fields to update.
`feedback`	string	No	Analyst feedback on the alert (e.g. `TRUE_POSITIVE`, `FALSE_POSITIVE`).

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001",
  "feedback": "TRUE_POSITIVE"
}

fetchRecommendation

Fetch an AI-generated triage recommendation for an alert.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts:fetchRecommendation
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001"
}

getAlertOverviewData

Get overview widget data for a specific alert.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts:getAlertOverviewData
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001"
}

moveAlert

Move an alert from one case to another.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts:move
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The source case ID.
`alertId`	string	Yes	The alert ID to move.
`destinationCaseId`	string	Yes	The target case ID the alert should be moved to.

Warning: Moving an alert is a mutating operation. The alert is removed from the source case and added to the destination case.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001",
  "destinationCaseId": "12346"
}

createRecommendationLongRunning

Start an asynchronous (long-running operation) AI recommendation job for an alert. Use this when the synchronous fetchRecommendation times out for complex alerts.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts:createRecommendationLongRunning
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	No	The alert ID. Omit to generate recommendations for all alerts in the case.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001"
}

pauseAlertSla

Pause the SLA countdown timer on a specific alert.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts:pauseSla
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.
`reason`	string	No	Reason for pausing (free text).

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001",
  "reason": "Escalated to tier 2"
}

resumeAlertSla

Resume a paused SLA timer on a specific alert.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts:resumeSla
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001"
}

setAlertSla

Assign a specific SLA definition to an alert, starting the SLA timer.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts:setSla
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.
`slaDefinitionId`	string	Yes	ID of the SLA definition to apply. Use `listSlaDefinitions` to get valid IDs.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001",
  "slaDefinitionId": "sla-uuid-here"
}

resolveAlertOverviewWidget

Dismiss a specific overview widget on an alert.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts:resolveOverviewWidget
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.
`widgetId`	string	No	The widget ID to resolve.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001",
  "widgetId": "widget-xyz"
}

addAlertTag

Add a tag to a case alert.

HTTP: POST /v1alpha/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts:addTag
API Version: v1alpha

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.
`tag`	string	Yes	Tag value to add.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001",
  "tag": "phishing"
}

removeAlertTag

Remove a tag from a case alert.

HTTP: DELETE /v1alpha/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts:removeTag
API Version: v1alpha

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.
`tag`	string	Yes	Tag value to remove.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001",
  "tag": "phishing"
}

listAlertViews

List available view configurations for case alerts.

HTTP: GET /v1alpha/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts:listAlertViews
API Version: v1alpha

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.

Example:

{
  "caseId": "12345"
}

connectorEvents

Raw event data from the SOAR connector pipeline, associated with case alerts.

getConnectorEvent

Get a specific raw connector event for an alert.

HTTP: GET /v1alpha/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts/connectorEvents
API Version: v1alpha

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.
`connectorEventId`	string	Yes	The connector event ID.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001",
  "connectorEventId": "event-001"
}

listConnectorEvents

List all raw connector events associated with an alert.

HTTP: GET /v1alpha/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts/connectorEvents
API Version: v1alpha

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.
`pageSize`	number	No	Maximum number of events to return.
`pageToken`	string	No	Pagination token.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001",
  "pageSize": 20
}

getFormattedConnectorEvent

Get a human-readable formatted representation of a connector event.

HTTP: GET /v1alpha/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts/connectorEvents:getFormatted
API Version: v1alpha

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.
`connectorEventId`	string	Yes	The connector event ID.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001",
  "connectorEventId": "event-001"
}

alertContextProperties

Key-value pairs that analysts can attach to alerts to store investigation-specific metadata.

createAlertContextProperty

Create a new key-value context property on an alert.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts/contextProperties
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.
`key`	string	Yes	Property key (e.g. `analyst_note`, `ticket_id`).
`value`	string	Yes	Property value.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001",
  "key": "jira_ticket",
  "value": "SEC-4321"
}

getAlertContextProperty

Retrieve a specific context property from an alert.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts/contextProperties
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.
`propertyId`	string	Yes	The context property ID.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001",
  "propertyId": "prop-001"
}

listAlertContextProperties

List all context properties on an alert.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts/contextProperties
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001"
}

updateAlertContextProperty

Update the value of an existing context property on an alert.

HTTP: PATCH /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts/contextProperties
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.
`propertyId`	string	Yes	The context property ID to update.
`value`	string	Yes	New value.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001",
  "propertyId": "prop-001",
  "value": "SEC-9999"
}

deleteAlertContextProperty

Delete a specific context property from an alert.

HTTP: DELETE /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts/contextProperties
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.
`propertyId`	string	Yes	The context property ID to delete.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001",
  "propertyId": "prop-001"
}

clearAllAlertContextProperties

Remove all context properties from an alert in one call.

HTTP: DELETE /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts/contextProperties:clearAll
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.

Warning: This permanently deletes all context properties on the alert. This action cannot be undone.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001"
}

alertCustomFieldValues

Custom field values (defined via customFields resource) attached to case alerts.

getAlertCustomFieldValue

Get the value of a specific custom field on an alert.

HTTP: GET /v1alpha/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts/customFieldValues
API Version: v1alpha

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.
`customFieldId`	string	Yes	The custom field definition ID.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001",
  "customFieldId": "field-uuid-here"
}

listAlertCustomFieldValues

List all custom field values on an alert.

HTTP: GET /v1alpha/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts/customFieldValues
API Version: v1alpha

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001"
}

updateAlertCustomFieldValue

Update the value of a single custom field on an alert.

HTTP: PATCH /v1alpha/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts/customFieldValues
API Version: v1alpha

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.
`customFieldId`	string	Yes	The custom field definition ID.
`value`	string	Yes	New value for the field.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001",
  "customFieldId": "field-uuid-here",
  "value": "Confirmed malicious"
}

batchUpdateAlertCustomFieldValues

Update multiple custom field values on an alert in a single API call.

HTTP: POST /v1alpha/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts/customFieldValues:batchUpdate
API Version: v1alpha

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.
`requests`	array	Yes	Array of update objects, each containing `customFieldId` and `value`.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001",
  "requests": [
    { "customFieldId": "field-001", "value": "Critical" },
    { "customFieldId": "field-002", "value": "2026-07-07" }
  ]
}

involvedEntities

Entities (hosts, users, IP addresses, file hashes, etc.) that are linked to an alert as participants in the security event.

addInvolvedEntity

Add an entity to a case alert as an involved entity.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts/involvedEntities
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.
`entityType`	string	Yes	Entity type (e.g. `IP`, `USER`, `HOSTNAME`, `FILE_HASH`).
`entityValue`	string	Yes	The entity identifier value (e.g. `192.168.1.1`, `[email protected]`).

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001",
  "entityType": "IP",
  "entityValue": "192.168.1.100"
}

getInvolvedEntity

Retrieve a specific involved entity from an alert.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts/involvedEntities
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.
`entityId`	string	Yes	The involved entity ID.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001",
  "entityId": "entity-uuid-here"
}

listInvolvedEntities

List all involved entities on an alert.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts/involvedEntities
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001"
}

updateInvolvedEntity

Update an involved entity record on an alert.

HTTP: PATCH /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts/involvedEntities
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.
`entityId`	string	Yes	The involved entity ID.
`updateMask`	string	No	Fields to update.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001",
  "entityId": "entity-uuid-here",
  "updateMask": "verdict"
}

fetchEntityCards

Fetch enrichment information cards for entities involved in an alert.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts/involvedEntities:fetchCards
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001"
}

addEntityProperty

Add a key-value property to an involved entity.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts/involvedEntities:addProperty
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.
`entityId`	string	Yes	The involved entity ID.
`key`	string	Yes	Property key.
`value`	string	Yes	Property value.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001",
  "entityId": "entity-uuid-here",
  "key": "threat_actor",
  "value": "APT29"
}

updateEntityProperty

Update an existing property on an involved entity.

HTTP: PATCH /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseAlerts/involvedEntities:updateProperty
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`alertId`	string	Yes	The alert ID.
`entityId`	string	Yes	The involved entity ID.
`key`	string	Yes	Property key to update.
`value`	string	Yes	New value.

Example:

{
  "caseId": "12345",
  "alertId": "alert-abc-001",
  "entityId": "entity-uuid-here",
  "key": "threat_actor",
  "value": "APT28"
}

caseComments

Analyst notes attached to a case.

createComment

Add a new comment to a case.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseComments
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`content`	string	Yes	Comment text (plain text or Markdown).

Example:

{
  "caseId": "12345",
  "content": "Confirmed malicious traffic to known C2 IP 198.51.100.10. Isolating host."
}

getComment

Retrieve a specific comment.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseComments
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`commentId`	string	Yes	The comment ID.

Example:

{
  "caseId": "12345",
  "commentId": "comment-001"
}

listComments

List all comments on a case.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseComments
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`pageSize`	number	No	Maximum comments to return.
`pageToken`	string	No	Pagination token.

Example:

{
  "caseId": "12345",
  "pageSize": 50
}

updateComment

Edit an existing comment.

HTTP: PATCH /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseComments
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`commentId`	string	Yes	The comment ID.
`content`	string	Yes	Updated comment text.

Example:

{
  "caseId": "12345",
  "commentId": "comment-001",
  "content": "Updated: Host isolated and forensic image taken."
}

deleteComment

Delete a comment from a case.

HTTP: DELETE /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseComments
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`commentId`	string	Yes	The comment ID to delete.

Example:

{
  "caseId": "12345",
  "commentId": "comment-001"
}

caseEvidenceData

Evidence data records collected during case investigation. This resource is read-only via the connector.

getCaseEvidenceData

Retrieve a specific evidence data record.

HTTP: GET /v1alpha/projects/{project}/locations/{location}/instances/{instance}/cases/caseEvidenceDatas
API Version: v1alpha

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`evidenceDataId`	string	Yes	The evidence data record ID.

Example:

{
  "caseId": "12345",
  "evidenceDataId": "evidence-001"
}

listCaseEvidenceData

List all evidence data records for a case.

HTTP: GET /v1alpha/projects/{project}/locations/{location}/instances/{instance}/cases/caseEvidenceDatas
API Version: v1alpha

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`pageSize`	number	No	Maximum records to return.
`pageToken`	string	No	Pagination token.

Example:

{
  "caseId": "12345"
}

caseWallRecords

The case activity wall (timeline) records every action taken on a case. This resource is read-only via the connector, except for the favoriteWallRecord action.

getWallRecord

Retrieve a specific wall record.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseWallRecords
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`wallRecordId`	string	Yes	The wall record ID.

Example:

{
  "caseId": "12345",
  "wallRecordId": "wall-001"
}

listWallRecords

List all activity wall records for a case (ordered chronologically).

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseWallRecords
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`pageSize`	number	No	Maximum records to return.
`pageToken`	string	No	Pagination token.

Example:

{
  "caseId": "12345",
  "pageSize": 100
}

favoriteWallRecord

Mark a wall record as a favourite for quick reference.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseWallRecords:favorite
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`wallRecordId`	string	Yes	The wall record ID to mark as favourite.

Example:

{
  "caseId": "12345",
  "wallRecordId": "wall-001"
}

fetchActivitiesCount

Get a count of activity records on the case wall.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/cases/caseWallRecords:fetchActivitiesCount
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.

Example:

{
  "caseId": "12345"
}

chatMessages

Real-time chat messages exchanged between analysts within a case.

sendChatMessage

Send a new chat message to a case.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases/chatMessages
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`message`	string	Yes	Message text to send.

Example:

{
  "caseId": "12345",
  "message": "@alice can you check the memory dump from host WS-042?"
}

getChatMessage

Retrieve a specific chat message.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/cases/chatMessages
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`messageId`	string	Yes	The message ID.

Example:

{
  "caseId": "12345",
  "messageId": "msg-001"
}

listChatMessages

List chat messages in a case.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/cases/chatMessages
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`pageSize`	number	No	Maximum messages to return.
`pageToken`	string	No	Pagination token.

Example:

{
  "caseId": "12345",
  "pageSize": 50
}

pinMessage

Pin a chat message so it appears prominently in the case.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases/chatMessages:pinMessage
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`messageId`	string	Yes	The message ID to pin.

Example:

{
  "caseId": "12345",
  "messageId": "msg-001"
}

unpinMessage

Unpin a previously pinned chat message.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases/chatMessages:unpinMessage
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`messageId`	string	Yes	The message ID to unpin.

Example:

{
  "caseId": "12345",
  "messageId": "msg-001"
}

getUnreadMessagesCount

Get the count of unread chat messages in a case for the authenticated user.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases/chatMessages:unreadMessagesCount
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.

Example:

{
  "caseId": "12345"
}

uploadAttachment

Upload a file attachment to the case chat.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases/chatMessages:upload
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`fileName`	string	Yes	File name including extension (e.g. `screenshot.png`).
`content`	string	Yes	Base64-encoded file content.

Example:

{
  "caseId": "12345",
  "fileName": "network_pcap.pcap",
  "content": "base64encodedcontent..."
}

downloadAttachment

Download a file attachment from the case chat.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases/chatMessages/attachments:download
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`messageId`	string	Yes	The message ID that contains the attachment.
`attachmentId`	string	Yes	The attachment ID.

Example:

{
  "caseId": "12345",
  "messageId": "msg-002",
  "attachmentId": "attach-001"
}

caseContextProperties

Key-value context properties attached at the case level (not alert level).

createCaseContextProperty

Create a new context property on a case.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/cases/contextProperties
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`key`	string	Yes	Property key.
`value`	string	Yes	Property value.

Example:

{
  "caseId": "12345",
  "key": "incident_ticket",
  "value": "INC-88432"
}

getCaseContextProperty

Retrieve a specific context property from a case.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/cases/contextProperties
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`propertyId`	string	Yes	The context property ID.

Example:

{
  "caseId": "12345",
  "propertyId": "prop-001"
}

listCaseContextProperties

List all context properties on a case.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/cases/contextProperties
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.

Example:

{
  "caseId": "12345"
}

updateCaseContextProperty

Update a context property value on a case.

HTTP: PATCH /v1/projects/{project}/locations/{location}/instances/{instance}/cases/contextProperties
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`propertyId`	string	Yes	The context property ID.
`value`	string	Yes	New value.

Example:

{
  "caseId": "12345",
  "propertyId": "prop-001",
  "value": "INC-88499"
}

deleteCaseContextProperty

Delete a specific context property from a case.

HTTP: DELETE /v1/projects/{project}/locations/{location}/instances/{instance}/cases/contextProperties
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`propertyId`	string	Yes	The context property ID to delete.

Example:

{
  "caseId": "12345",
  "propertyId": "prop-001"
}

clearAllCaseContextProperties

Remove all context properties from a case in one call.

HTTP: DELETE /v1/projects/{project}/locations/{location}/instances/{instance}/cases/contextProperties:clearAll
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.

Warning: Permanently removes all context properties from the case. Cannot be undone.

Example:

{
  "caseId": "12345"
}

caseCustomFieldValues

Custom field values (defined via customFields) attached at the case level.

getCaseCustomFieldValue

Get a specific custom field value on a case.

HTTP: GET /v1alpha/projects/{project}/locations/{location}/instances/{instance}/cases/customFieldValues
API Version: v1alpha

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`customFieldId`	string	Yes	The custom field definition ID.

Example:

{
  "caseId": "12345",
  "customFieldId": "field-uuid-here"
}

listCaseCustomFieldValues

List all custom field values on a case.

HTTP: GET /v1alpha/projects/{project}/locations/{location}/instances/{instance}/cases/customFieldValues
API Version: v1alpha

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.

Example:

{
  "caseId": "12345"
}

updateCaseCustomFieldValue

Update a single custom field value on a case.

HTTP: PATCH /v1alpha/projects/{project}/locations/{location}/instances/{instance}/cases/customFieldValues
API Version: v1alpha

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`customFieldId`	string	Yes	The custom field definition ID.
`value`	string	Yes	New value.

Example:

{
  "caseId": "12345",
  "customFieldId": "field-uuid-here",
  "value": "Tier 1"
}

batchUpdateCaseCustomFieldValues

Update multiple custom field values on a case in one call.

HTTP: POST /v1alpha/projects/{project}/locations/{location}/instances/{instance}/cases/customFieldValues:batchUpdate
API Version: v1alpha

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`requests`	array	Yes	Array of update objects, each containing `customFieldId` and `value`.

Example:

{
  "caseId": "12345",
  "requests": [
    { "customFieldId": "field-001", "value": "Critical" },
    { "customFieldId": "field-002", "value": "Ransomware" }
  ]
}

customFields

Schema definitions for custom fields that can be attached to cases and alerts. Manage these definitions before using caseCustomFieldValues or alertCustomFieldValues.

createCustomField

Create a new custom field definition.

HTTP: POST /v1alpha/projects/{project}/locations/{location}/instances/{instance}/customFields
API Version: v1alpha

Parameter	Type	Required	Description
`displayName`	string	Yes	Human-readable label shown in the Google SecOps UI.
`fieldType`	string	Yes	Data type: `STRING`, `NUMBER`, `BOOLEAN`, or `DATE`.
`entityType`	string	Yes	Which entity this field applies to: `CASE` or `ALERT`.
`description`	string	No	Description of the field's purpose.

Example:

{
  "displayName": "Business Impact",
  "fieldType": "STRING",
  "entityType": "CASE",
  "description": "Estimated business impact of the incident"
}

getCustomField

Retrieve a custom field definition.

HTTP: GET /v1alpha/projects/{project}/locations/{location}/instances/{instance}/customFields
API Version: v1alpha

Parameter	Type	Required	Description
`customFieldId`	string	Yes	The custom field definition ID.

Example:

{
  "customFieldId": "field-uuid-here"
}

listCustomFields

List all custom field definitions for the instance.

HTTP: GET /v1alpha/projects/{project}/locations/{location}/instances/{instance}/customFields
API Version: v1alpha

Parameter	Type	Required	Description
`pageSize`	number	No	Maximum fields to return.
`pageToken`	string	No	Pagination token.

Example:

{
  "pageSize": 50
}

updateCustomField

Update a custom field definition.

HTTP: PATCH /v1alpha/projects/{project}/locations/{location}/instances/{instance}/customFields
API Version: v1alpha

Parameter	Type	Required	Description
`customFieldId`	string	Yes	The custom field definition ID.
`displayName`	string	No	New display name.
`description`	string	No	New description.

Example:

{
  "customFieldId": "field-uuid-here",
  "displayName": "Business Impact Level"
}

deleteCustomField

Delete a custom field definition and all its values across cases and alerts.

HTTP: DELETE /v1alpha/projects/{project}/locations/{location}/instances/{instance}/customFields
API Version: v1alpha

Parameter	Type	Required	Description
`customFieldId`	string	Yes	The custom field definition ID to delete.

Warning: Deleting a custom field definition also deletes all values stored for that field across all cases and alerts. This cannot be undone.

Example:

{
  "customFieldId": "field-uuid-here"
}

caseCloseDefinitions

Definitions that represent the reasons or categories under which a case can be closed (e.g. "True Positive", "False Positive", "Duplicate").

createCaseCloseDefinition

Create a new close definition.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/caseCloseDefinitions
API Version: v1

Parameter	Type	Required	Description
`displayName`	string	Yes	Display name (e.g. `False Positive`).
`description`	string	No	Description of when to use this close reason.

Example:

{
  "displayName": "False Positive",
  "description": "Alert was triggered in error with no actual threat"
}

getCaseCloseDefinition

Retrieve a specific close definition.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/caseCloseDefinitions
API Version: v1

Parameter	Type	Required	Description
`closeDefinitionId`	string	Yes	The close definition ID.

Example:

{
  "closeDefinitionId": "close-def-uuid"
}

listCaseCloseDefinitions

List all close definitions for the instance.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/caseCloseDefinitions
API Version: v1

Parameter	Type	Required	Description
`pageSize`	number	No	Maximum definitions to return.
`pageToken`	string	No	Pagination token.

Example:

{
  "pageSize": 25
}

updateCaseCloseDefinition

Update a close definition.

HTTP: PATCH /v1/projects/{project}/locations/{location}/instances/{instance}/caseCloseDefinitions
API Version: v1

Parameter	Type	Required	Description
`closeDefinitionId`	string	Yes	The close definition ID.
`displayName`	string	No	New display name.
`description`	string	No	New description.

Example:

{
  "closeDefinitionId": "close-def-uuid",
  "displayName": "Confirmed False Positive"
}

deleteCaseCloseDefinition

Delete a close definition.

HTTP: DELETE /v1/projects/{project}/locations/{location}/instances/{instance}/caseCloseDefinitions
API Version: v1

Parameter	Type	Required	Description
`closeDefinitionId`	string	Yes	The close definition ID to delete.

Warning: Deleting a close definition that is in use by existing cases may cause data integrity issues in the Google SecOps UI.

Example:

{
  "closeDefinitionId": "close-def-uuid"
}

caseQueueFilters

Saved filter configurations that analysts use to segment their case queues. Supports sharing configurations.

createCaseQueueFilter

Create a new saved queue filter.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/caseQueueFilters
API Version: v1

Parameter	Type	Required	Description
`displayName`	string	Yes	Filter name shown in the Google SecOps UI.
`filter`	string	Yes	Filter expression (e.g. `priority = "HIGH" AND status = "OPEN"`).

Example:

{
  "displayName": "My High Priority Open Cases",
  "filter": "priority = \"HIGH\" AND status = \"OPEN\""
}

getCaseQueueFilter

Retrieve a specific queue filter.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/caseQueueFilters
API Version: v1

Parameter	Type	Required	Description
`filterId`	string	Yes	The queue filter ID.

Example:

{
  "filterId": "filter-uuid"
}

listCaseQueueFilters

List all saved queue filters for the instance.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/caseQueueFilters
API Version: v1

Parameter	Type	Required	Description
`pageSize`	number	No	Maximum filters to return.
`pageToken`	string	No	Pagination token.

Example:

{
  "pageSize": 50
}

updateCaseQueueFilter

Update a queue filter.

HTTP: PATCH /v1/projects/{project}/locations/{location}/instances/{instance}/caseQueueFilters
API Version: v1

Parameter	Type	Required	Description
`filterId`	string	Yes	The queue filter ID.
`displayName`	string	No	New display name.
`filter`	string	No	Updated filter expression.

Example:

{
  "filterId": "filter-uuid",
  "filter": "priority = \"CRITICAL\" AND status = \"OPEN\""
}

deleteCaseQueueFilter

Delete a saved queue filter.

HTTP: DELETE /v1/projects/{project}/locations/{location}/instances/{instance}/caseQueueFilters
API Version: v1

Parameter	Type	Required	Description
`filterId`	string	Yes	The queue filter ID to delete.

Example:

{
  "filterId": "filter-uuid"
}

getShareConfig

Get the sharing configuration for a queue filter (controls which teams can see it).

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/caseQueueFilters:getShareConfig
API Version: v1

Parameter	Type	Required	Description
`filterId`	string	Yes	The queue filter ID.

Example:

{
  "filterId": "filter-uuid"
}

updateShareConfig

Update the sharing configuration for a queue filter.

HTTP: PATCH /v1/projects/{project}/locations/{location}/instances/{instance}/caseQueueFilters:updateShareConfig
API Version: v1

Parameter	Type	Required	Description
`filterId`	string	Yes	The queue filter ID.
`shareConfig`	object	Yes	Sharing configuration object (refer to Google SecOps API docs for schema).

Example:

{
  "filterId": "filter-uuid",
  "shareConfig": {
    "shareWithAll": true
  }
}

caseStageDefinitions

Workflow stage definitions that represent phases in the investigation lifecycle (e.g. "Initial Triage", "Investigation", "Containment", "Recovery").

createCaseStageDefinition

Create a new stage definition.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/caseStageDefinitions
API Version: v1

Parameter	Type	Required	Description
`displayName`	string	Yes	Stage name (e.g. `Containment`).
`description`	string	No	Description of this stage.

Example:

{
  "displayName": "Containment",
  "description": "Active measures taken to limit the spread of the threat"
}

getCaseStageDefinition

Retrieve a specific stage definition.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/caseStageDefinitions
API Version: v1

Parameter	Type	Required	Description
`stageDefinitionId`	string	Yes	The stage definition ID.

Example:

{
  "stageDefinitionId": "stage-uuid"
}

listCaseStageDefinitions

List all stage definitions for the instance.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/caseStageDefinitions
API Version: v1

Parameter	Type	Required	Description
`pageSize`	number	No	Maximum stages to return.
`pageToken`	string	No	Pagination token.

Example:

{}

updateCaseStageDefinition

Update a stage definition.

HTTP: PATCH /v1/projects/{project}/locations/{location}/instances/{instance}/caseStageDefinitions
API Version: v1

Parameter	Type	Required	Description
`stageDefinitionId`	string	Yes	The stage definition ID.
`displayName`	string	No	New display name.
`description`	string	No	New description.

Example:

{
  "stageDefinitionId": "stage-uuid",
  "displayName": "Active Containment"
}

deleteCaseStageDefinition

Delete a stage definition.

HTTP: DELETE /v1/projects/{project}/locations/{location}/instances/{instance}/caseStageDefinitions
API Version: v1

Parameter	Type	Required	Description
`stageDefinitionId`	string	Yes	The stage definition ID to delete.

Example:

{
  "stageDefinitionId": "stage-uuid"
}

caseTagDefinitions

The taxonomy of valid tags that can be applied to cases and alerts. Tags must be defined here before they can be used in addTag operations.

createCaseTagDefinition

Create a new tag definition.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/caseTagDefinitions
API Version: v1

Parameter	Type	Required	Description
`value`	string	Yes	Tag value/name (e.g. `ransomware`, `data-exfiltration`).
`description`	string	No	Description of when to use this tag.

Example:

{
  "value": "ransomware",
  "description": "Case involves ransomware infection or attack"
}

getCaseTagDefinition

Retrieve a specific tag definition.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/caseTagDefinitions
API Version: v1

Parameter	Type	Required	Description
`tagDefinitionId`	string	Yes	The tag definition ID.

Example:

{
  "tagDefinitionId": "tag-def-uuid"
}

listCaseTagDefinitions

List all tag definitions for the instance.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/caseTagDefinitions
API Version: v1

Parameter	Type	Required	Description
`pageSize`	number	No	Maximum definitions to return.
`pageToken`	string	No	Pagination token.

Example:

{}

updateCaseTagDefinition

Update a tag definition.

HTTP: PATCH /v1/projects/{project}/locations/{location}/instances/{instance}/caseTagDefinitions
API Version: v1

Parameter	Type	Required	Description
`tagDefinitionId`	string	Yes	The tag definition ID.
`value`	string	No	New tag value.
`description`	string	No	New description.

Example:

{
  "tagDefinitionId": "tag-def-uuid",
  "description": "Ransomware or wiper malware attack"
}

deleteCaseTagDefinition

Delete a tag definition.

HTTP: DELETE /v1/projects/{project}/locations/{location}/instances/{instance}/caseTagDefinitions
API Version: v1

Parameter	Type	Required	Description
`tagDefinitionId`	string	Yes	The tag definition ID to delete.

Warning: Deleting a tag definition does not automatically remove that tag from existing cases. Ensure you clean up tag assignments before deleting the definition.

Example:

{
  "tagDefinitionId": "tag-def-uuid"
}

importCaseTagDefinitions

Bulk import multiple tag definitions in a single call.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/caseTagDefinitions:import
API Version: v1

Parameter	Type	Required	Description
`tagDefinitions`	array	Yes	Array of tag definition objects, each with at minimum a `value` field.

Example:

{
  "tagDefinitions": [
    { "value": "malware", "description": "Malware infection" },
    { "value": "phishing", "description": "Phishing attack vector" },
    { "value": "insider-threat", "description": "Potential insider threat" }
  ]
}

slaDefinitions

SLA (Service Level Agreement) definitions specify the time targets for case or alert resolution.

createSlaDefinition

Create a new SLA definition.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/slaDefinitions
API Version: v1

Parameter	Type	Required	Description
`displayName`	string	Yes	SLA name (e.g. `P1 — 4 Hour Response`).
`duration`	string	Yes	SLA duration in seconds format (e.g. `"14400s"` for 4 hours, `"86400s"` for 24 hours).
`description`	string	No	Description of the SLA requirements.

Example:

{
  "displayName": "P1 — 4 Hour Response",
  "duration": "14400s",
  "description": "Critical incidents must be resolved within 4 hours"
}

getSlaDefinition

Retrieve a specific SLA definition.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/slaDefinitions
API Version: v1

Parameter	Type	Required	Description
`slaDefinitionId`	string	Yes	The SLA definition ID.

Example:

{
  "slaDefinitionId": "sla-uuid"
}

listSlaDefinitions

List all SLA definitions for the instance.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/slaDefinitions
API Version: v1

Parameter	Type	Required	Description
`pageSize`	number	No	Maximum definitions to return.
`pageToken`	string	No	Pagination token.

Example:

{}

updateSlaDefinition

Update an SLA definition.

HTTP: PATCH /v1/projects/{project}/locations/{location}/instances/{instance}/slaDefinitions
API Version: v1

Parameter	Type	Required	Description
`slaDefinitionId`	string	Yes	The SLA definition ID.
`displayName`	string	No	New display name.
`duration`	string	No	New duration (e.g. `"7200s"` for 2 hours).

Example:

{
  "slaDefinitionId": "sla-uuid",
  "duration": "7200s"
}

exportSlaDefinitions

Export all SLA definitions to a portable format (e.g. for backup or migration).

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/slaDefinitions:export
API Version: v1

This operation takes no parameters.

Example:

{}

importSlaDefinitions

Bulk import SLA definitions, useful for migration or configuration-as-code workflows.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/slaDefinitions:import
API Version: v1

Parameter	Type	Required	Description
`slaDefinitions`	array	Yes	Array of SLA definition objects (each with `displayName`, `duration`, and optionally `description`).

Example:

{
  "slaDefinitions": [
    { "displayName": "P1 — 4 Hours", "duration": "14400s" },
    { "displayName": "P2 — 24 Hours", "duration": "86400s" }
  ]
}

deleteSlaDefinition

Delete an SLA definition.

HTTP: DELETE /v1/projects/{project}/locations/{location}/instances/{instance}/slaDefinitions
API Version: v1

Parameter	Type	Required	Description
`slaDefinitionId`	string	Yes	The SLA definition ID to delete.

Warning: Deleting an SLA definition that is currently assigned to active cases or alerts will stop SLA tracking for those items.

Example:

{
  "slaDefinitionId": "sla-uuid"
}

tasks

Tasks are action items assigned to analysts within a case.

createTask

Create a new task for a case.

HTTP: POST /v1/projects/{project}/locations/{location}/instances/{instance}/tasks
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID the task belongs to.
`displayName`	string	Yes	Task name (e.g. `Isolate affected host`).
`description`	string	No	Detailed task instructions.
`assignee`	object	No	User to assign (e.g. `{"user": {"email": "[email protected]"}}`).
`dueTime`	string	No	Due date/time in RFC3339 format (e.g. `2026-07-08T17:00:00Z`).

Example:

{
  "caseId": "12345",
  "displayName": "Isolate affected host WS-042",
  "description": "Network isolate host WS-042 via EDR. Confirm isolation before proceeding.",
  "assignee": { "user": { "email": "[email protected]" } },
  "dueTime": "2026-07-08T17:00:00Z"
}

getTask

Retrieve a specific task.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/tasks
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`taskId`	string	Yes	The task ID.

Example:

{
  "caseId": "12345",
  "taskId": "task-001"
}

listTasks

List all tasks for a case.

HTTP: GET /v1/projects/{project}/locations/{location}/instances/{instance}/tasks
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`pageSize`	number	No	Maximum tasks to return.
`pageToken`	string	No	Pagination token.

Example:

{
  "caseId": "12345"
}

updateTask

Update a task (e.g. mark it complete, reassign it, or change the due date).

HTTP: PATCH /v1/projects/{project}/locations/{location}/instances/{instance}/tasks
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`taskId`	string	Yes	The task ID.
`updateMask`	string	No	Fields to update (e.g. `status,assignee`).
`status`	string	No	Task status (e.g. `COMPLETED`, `IN_PROGRESS`, `OPEN`).
`displayName`	string	No	Updated task name.

Example:

{
  "caseId": "12345",
  "taskId": "task-001",
  "status": "COMPLETED"
}

deleteTask

Delete a task from a case.

HTTP: DELETE /v1/projects/{project}/locations/{location}/instances/{instance}/tasks
API Version: v1

Parameter	Type	Required	Description
`caseId`	string	Yes	The case ID.
`taskId`	string	Yes	The task ID to delete.

Example:

{
  "caseId": "12345",
  "taskId": "task-001"
}

Common Workflows

Triage a new case end-to-end

cases.listCases         → filter: status = "OPEN" AND priority = "HIGH", pageSize = 10
cases.getCase           → retrieve full details of the first result
caseAlerts.listCaseAlerts → get all alerts in the case
caseAlerts.fetchRecommendation → for each alert, fetch the AI recommendation
involvedEntities.listInvolvedEntities → enumerate entities for the highest-risk alert
involvedEntities.fetchEntityCards → enrich each involved entity
cases.addTag            → tag the case with the threat category (e.g. "ransomware")
tasks.createTask        → create a containment task and assign to analyst
caseComments.createComment → add investigation note with findings
cases.pauseSla          → pause SLA if waiting for customer confirmation

Close cases in bulk after false positive review

1. caseCloseDefinitions.listCaseCloseDefinitions
   → find the "False Positive" close definition ID
2. cases.listCases
   → filter: tag = "false-positive" AND status = "OPEN"
   → collect case IDs
3. cases.executeBulkClose
   → caseIds: [list from step 2], closeDefinitionId: [ID from step 1]

Set up custom fields for a new deployment

customFields.createCustomField → create "Affected System" (STRING, CASE)
customFields.createCustomField → create "Attack Vector" (STRING, CASE)
customFields.createCustomField → create "Business Impact" (STRING, CASE)
customFields.listCustomFields  → verify all three are created and note their IDs
slaDefinitions.createSlaDefinition → "P1 — 4 Hours" with duration "14400s"
slaDefinitions.createSlaDefinition → "P2 — 24 Hours" with duration "86400s"
caseTagDefinitions.importCaseTagDefinitions → bulk import your tag taxonomy
caseStageDefinitions.createCaseStageDefinition → create workflow stages
caseCloseDefinitions.createCaseCloseDefinition → create close reasons

Annotate a case with external ticket correlation

1. caseContextProperties.createCaseContextProperty
   → key: "jira_ticket", value: "SEC-4321", caseId: "12345"
2. caseContextProperties.createCaseContextProperty
   → key: "pagerduty_incident", value: "PD-78901", caseId: "12345"
3. tasks.createTask
   → displayName: "Link Google SecOps findings to JIRA SEC-4321"
   → dueTime: "2026-07-09T09:00:00Z"

Best Practices

Always use listCaseCloseDefinitions before closing cases: The closeDefinitionId parameter in executeBulkClose must refer to a valid definition. Fetch the list once and cache the IDs in your workflow.
Use updateMask on PATCH operations: The updateMask parameter tells the API exactly which fields to update. Omitting it may cause unexpected overwrites if the API applies default field-clearing behaviour.
Prefer batchUpdate for custom fields: When you need to update multiple custom field values on the same resource, use batchUpdateCaseCustomFieldValues or batchUpdateAlertCustomFieldValues instead of making individual PATCH calls. This reduces latency and API quota usage.
Handle pagination for list operations: All list operations return a nextPageToken when more results are available. In long-running workflows always loop using pageToken until the response contains no nextPageToken.
Use countPriorities for dashboard automation: The countPriorities operation is efficient for building summary dashboards — it returns counts grouped by priority without fetching all case objects.
Respect the tag taxonomy: Tags applied via addTag must exist as caseTagDefinitions. Pre-populate the taxonomy using importCaseTagDefinitions before running automated tagging workflows.
Avoid mutating operations in read-only workflows: The chronicle.viewer IAM role is sufficient for all GET and LIST operations. Separate read credentials from write credentials in your credential store and use the minimum permission level required for each workflow.
The caseId field is passed as a query parameter for GET operations and in the body for POST/PATCH/DELETE: This is handled transparently by the connector, but be aware of this when reading API-level documentation.
SLA timers are instance-scoped: SLA definitions are global to the instance. Changes to a definition affect all cases and alerts currently assigned that SLA.
AI features require feature enablement: getOrCreateCaseSummary, fetchRecommendation, and createInsight depend on Google SecOps AI features being enabled on your instance. These operations return FAILED_PRECONDITION if the feature is not available. Use skipOnFeatureNotEnabled logic in automated workflows.

Troubleshooting

Error	Status	Likely Cause	Resolution
`UNAUTHENTICATED`	401	Service account JSON is invalid, corrupted, or the key has been revoked.	Regenerate the service account key in GCP Console and update the credential in NINA.
`PERMISSION_DENIED`	403	Service account lacks the required Google SecOps IAM role, or is trying to access a resource in a different project.	Grant `roles/chronicle.viewer` or `roles/chronicle.editor` to the service account in the GCP project that owns the Google SecOps instance.
`NOT_FOUND`	404	The specified case ID, alert ID, definition ID, or instance ID does not exist.	Verify the ID with a list operation first. Confirm `project`, `location`, and `instance` credential values match the target Google SecOps instance.
`INVALID_ARGUMENT`	400	A required parameter is missing, a filter expression is malformed, or an ID references a non-existent resource.	Check all required parameters are provided. Validate filter syntax. Use list operations to retrieve valid IDs.
`FAILED_PRECONDITION`	400	AI feature not enabled on the instance (`getOrCreateCaseSummary`, `fetchRecommendation`), or an operation precondition is not satisfied (e.g. closing an already-closed case).	Check if the Google SecOps AI feature is enabled in your Google SecOps instance settings. Contact your Google SecOps account team if it should be available.
`ALREADY_EXISTS`	409	Attempting to create a resource that already exists (e.g. a tag definition with the same value).	Use list operations to check for existing resources before creating.
`Too Many Requests`	429	Google SecOps API quota exceeded.	The connector retries automatically up to 3 times with exponential back-off. If it persists, reduce workflow parallelism or request a quota increase via Google Cloud Console.
Connection timeout	—	Network issue, or the `region` credential value points to the wrong Google SecOps API endpoint.	Verify the `region` value is correct for your Google SecOps deployment. Test network connectivity to `https://{region}-chronicle.googleapis.com`.
`invalid service account JSON`	—	The `serviceAccountJson` credential field contains malformed JSON, or contains a user account key instead of a service account key.	The JSON must have `"type": "service_account"`. Re-download the key from GCP Console. Ensure the full JSON content is pasted (not just part of it).
Wrong region	—	API returns 404 for the instance path even though the instance UUID is correct.	The `region`, `location`, `project`, and `instance` values must all match. A mismatch between `region` (API hostname) and `location` (resource path) is the most common cause.

Verifying credentials manually

To confirm the service account and instance values are correct before creating a NINA credential, you can test with curl:

# Set variables
PROJECT="your-gcp-project-id"
LOCATION="eu"
INSTANCE="your-instance-uuid"
REGION="eu"
SA_KEY_FILE="/path/to/key.json"

# Obtain a token
TOKEN=$(python3 -c "
import google.oauth2.service_account as sa
import google.auth.transport.requests as req
creds = sa.Credentials.from_service_account_file(
    '$SA_KEY_FILE',
    scopes=['https://www.googleapis.com/auth/cloud-platform']
)
creds.refresh(req.Request())
print(creds.token)
")

# List cases (should return 200 with a cases array or empty object)
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://$REGION-chronicle.googleapis.com/v1/projects/$PROJECT/locations/$LOCATION/instances/$INSTANCE/cases?pageSize=1"

A 200 response with a JSON body (even {} or {"cases":[]}) confirms all four credential fields are correct. Any other status code indicates a misconfiguration.

Running the integration tests

export CHRONICLE_SERVICE_ACCOUNT_JSON=$(cat /path/to/key.json)
export CHRONICLE_REGION=eu
export CHRONICLE_PROJECT=your-gcp-project-id
export CHRONICLE_LOCATION=eu
export CHRONICLE_INSTANCE=your-instance-uuid

go test -v -count=1 -timeout 120s ./internal/integrations/chronicle-cases/...

Generating an evidence report

./scripts/generate-evidence.sh chronicle-cases

The report is written to evidence/chronicle-cases/<date>-chronicle-cases-report.md.

Support

For issues with this integration, provide the following when contacting support:

The resource and operation name (e.g. cases.listCases)
The full error message received (e.g. Google SecOps API error [NOT_FOUND / HTTP 404]: ...)
The Google SecOps API region, project, and instance (never share the service account JSON key)
Whether the issue is consistent or intermittent

For Google SecOps API reference documentation, refer to:

Google SecOps API reference: https://cloud.google.com/chronicle/docs/reference/rest
Google SecOps Cases API: https://cloud.google.com/chronicle/docs/reference/rest/v1/projects.locations.instances.cases
IAM roles for Google SecOps: https://cloud.google.com/iam/docs/understanding-roles#chronicle-roles
Google service account documentation: https://cloud.google.com/iam/docs/service-accounts

Updated: 2026-07-07

Overview​

Capabilities​

API Versions​

Credential Configuration​

Authentication Method​

How Authentication Works​

Google SecOps API Regions​

How to Obtain a Service Account Key​

Step 1 — Identify or create the service account​

Step 2 — Grant the required IAM role​

Step 3 — Create a JSON key​

Step 4 — Locate your Google SecOps instance details​

Creating a Google SecOps Cases Credential in NINA​

Rate Limits and Quotas​

Supported Operations​

Resources overview​

Operation Details​

cases​

getCase​

listCases​

updateCase​

addTag​

removeTag​

createInsight​

executeBulkAddTag​

executeBulkAssign​

executeBulkChangePriority​

executeBulkChangeStage​

executeBulkClose​

executeBulkReopen​

generateReport​

getCaseOverviewData​

merge​

pauseSla​

resumeSla​

resolveOverviewWidget​

countPriorities​

getOrCreateCaseSummary​

caseAlerts​

getCaseAlert​

listCaseAlerts​

updateCaseAlert​

fetchRecommendation​

getAlertOverviewData​

moveAlert​

createRecommendationLongRunning​

pauseAlertSla​

resumeAlertSla​

setAlertSla​

resolveAlertOverviewWidget​

addAlertTag​

removeAlertTag​

listAlertViews​

connectorEvents​

getConnectorEvent​

listConnectorEvents​

getFormattedConnectorEvent​

alertContextProperties​

createAlertContextProperty​

getAlertContextProperty​

listAlertContextProperties​

updateAlertContextProperty​

deleteAlertContextProperty​

clearAllAlertContextProperties​

alertCustomFieldValues​

getAlertCustomFieldValue​

listAlertCustomFieldValues​

updateAlertCustomFieldValue​

batchUpdateAlertCustomFieldValues​

involvedEntities​

addInvolvedEntity​

getInvolvedEntity​

listInvolvedEntities​

updateInvolvedEntity​

fetchEntityCards​

addEntityProperty​

updateEntityProperty​

caseComments​

createComment​

getComment​

Overview

Capabilities

API Versions

Credential Configuration

Authentication Method

How Authentication Works

Google SecOps API Regions

How to Obtain a Service Account Key

Step 1 — Identify or create the service account

Step 2 — Grant the required IAM role

Step 3 — Create a JSON key

Step 4 — Locate your Google SecOps instance details

Creating a Google SecOps Cases Credential in NINA

Rate Limits and Quotas

Supported Operations

Resources overview

Operation Details

cases

getCase

listCases

updateCase

addTag

removeTag

createInsight

executeBulkAddTag

executeBulkAssign

executeBulkChangePriority

executeBulkChangeStage

executeBulkClose

executeBulkReopen

generateReport

getCaseOverviewData

merge

pauseSla

resumeSla

resolveOverviewWidget

countPriorities

getOrCreateCaseSummary

caseAlerts

getCaseAlert

listCaseAlerts

updateCaseAlert

fetchRecommendation

getAlertOverviewData

moveAlert

createRecommendationLongRunning

pauseAlertSla

resumeAlertSla

setAlertSla

resolveAlertOverviewWidget

addAlertTag

removeAlertTag

listAlertViews

connectorEvents

getConnectorEvent

listConnectorEvents

getFormattedConnectorEvent

alertContextProperties

createAlertContextProperty

getAlertContextProperty

listAlertContextProperties

updateAlertContextProperty

deleteAlertContextProperty

clearAllAlertContextProperties

alertCustomFieldValues

getAlertCustomFieldValue

listAlertCustomFieldValues

updateAlertCustomFieldValue

batchUpdateAlertCustomFieldValues

involvedEntities

addInvolvedEntity

getInvolvedEntity

listInvolvedEntities

updateInvolvedEntity

fetchEntityCards

addEntityProperty

updateEntityProperty

caseComments

createComment

getComment