Google SecOps Integrations Integration Guide

Overview

The Google SecOps Integrations connector allows NINA to interact with the Google SecOps SOAR Integrations API. It covers the full lifecycle of SOAR integrations, their sub-components (actions, connectors, jobs, logical operators, managers, transformers), marketplace browsing, and remote agent management.

This connector is the SOAR layer of Google SecOps — it manages the automation building blocks that run inside the Google SecOps SOAR engine, as opposed to the security data layer covered by chronicle-events, chronicle-detections, chronicle-cases, and chronicle-instances.

Capabilities

Category	Resources	Operations
Integrations	integrations	Create, delete, get, list, import, export, push to production/staging, download, upload, fetch diffs and dependencies
Integration Actions	integrationActions, integrationActionRevisions	Full lifecycle of SOAR actions and their revisions; test execution; environment-scoped fetch
Connectors	connectors, connectorRevisions, connectorInstances, connectorInstanceLogs, connectorContextProperties	Full lifecycle of SOAR connectors, their instances, logs, context properties, and revisions
Integration Instances	integrationInstances	Create, delete, get, list, update, test, and fetch default instance
Jobs	jobs, jobRevisions, jobInstances, jobInstanceLogs, jobContextProperties	Full lifecycle of SOAR jobs, their revisions, instances, logs, and context properties
Logical Operators	logicalOperators, logicalOperatorRevisions	CRUD logical operators and their revisions; test execution
Managers	managers, managerRevisions	CRUD integration managers and their revisions; template retrieval
Transformers	transformers, transformerRevisions	CRUD transformers and their revisions; test execution
Marketplace	marketplaceIntegrations	Browse, install, and uninstall marketplace integrations
Remote Agents	remoteAgents	Full lifecycle of remote agents: create, delete, get, list, update, redeploy, upgrade, migrate connectors, fetch installer

API Version

All operations in this connector are served at /v1 of the Google SecOps API. The URL structure is:

https://{region}-chronicle.googleapis.com
  /v1/projects/{project}/locations/{location}/instances/{instance}
  /{resource}[/{subresource}][:{action}]

Unlike chronicle-events and chronicle-detections which use mixed v1/v1alpha paths, all chronicle-integrations operations resolve to /v1/ paths regardless of the API version column in the source mapping (the actual live endpoint is always /v1/).

Authentication Method

Google Cloud service account with a JSON key. The connector uses golang.org/x/oauth2/google JWT flow to obtain short-lived OAuth2 access tokens automatically. No user interaction, redirect URLs, or refresh tokens are required.

How Authentication Works

1. The connector reads the service account JSON key from the serviceAccountJson credential field.
2. It calls google.JWTConfigFromJSON to parse the key and requests the scope https://www.googleapis.com/auth/cloud-platform.
3. An OAuth2 HTTP client is created; it fetches and caches access tokens, refreshing them before expiry.
4. Every API request carries a Bearer <token> Authorization header added transparently.

---

Credential Configuration

Google SecOps API Regions

region value	API base URL	Geography
us	https://us-chronicle.googleapis.com	United States
eu	https://eu-chronicle.googleapis.com	Europe
asia-southeast1	https://asia-southeast1-chronicle.googleapis.com	Singapore
asia-south1	https://asia-south1-chronicle.googleapis.com	India
northamerica-northeast2	https://northamerica-northeast2-chronicle.googleapis.com	Canada
me-west1	https://me-west1-chronicle.googleapis.com	Middle East

Important: region and location are distinct fields. region is the hostname prefix used to build the API base URL. location is the GCP resource location embedded in the resource path. For most Google SecOps instances these share the same short value (e.g. both eu), but they can differ (e.g. region=eu, location=europe-west2). Always check the Google SecOps Console for the exact values for your instance.

Credential Fields

Field	Type	Required	Description	Example
serviceAccountJson	string	Yes	Complete Google service account JSON key — paste the entire downloaded JSON file content	{ "type": "service_account", "project_id": "my-project", ... }
region	string	Yes	Google SecOps API region prefix used to build the base URL	eu
project	string	Yes	GCP project ID	my-project-123
location	string	Yes	GCP location for the Google SecOps instance resource path	eu or europe-west2
instance	string	Yes	Google SecOps instance UUID	fca7f167-b9d1-43b1-9d03-0257d31dcb63

Where to Find These Values

Field	Where to find it
project	GCP Console → top navigation bar → project selector → Project ID (not the project name or number)
location	Google SecOps Console → Settings → Instance details → Location field
instance	Google SecOps Console → Settings → Instance details → Instance ID field (UUID format)
region	Google SecOps Console → Settings → Instance details → Region field — use the short prefix (e.g. eu, not europe)
serviceAccountJson	GCP Console → IAM & Admin → Service Accounts → select account → Keys tab → Add Key → JSON (full file content)

Required IAM Roles

The service account must be granted Google SecOps-specific IAM roles at the GCP project or Google SecOps instance level. Apply the minimum set of roles needed for your use case.

Role	GCP Role ID	Required for
Google SecOps Viewer	roles/chronicle.viewer	All read-only operations: list, get, fetch*, getFetch*
Google SecOps Editor	roles/chronicle.editor	Write operations: create, update, import, upload, pushToStaging, pushToProduction
Google SecOps Admin	roles/chronicle.admin	Destructive operations: delete, clearAll, uninstall, rollback, as well as remote agent management (redeploy, upgrade, migrate)
Google SecOps SOAR Admin	roles/chronicle.soarAdmin	SOAR-specific management: managing remote agents, connector instances, installing marketplace integrations

Least-privilege recommendations:

• Read-only monitoring / audit workflows: roles/chronicle.viewer
• Integration development (create/update integrations, actions, connectors): roles/chronicle.editor
• Full integration lifecycle including marketplace and remote agents: roles/chronicle.admin + roles/chronicle.soarAdmin
• Production promotion only: roles/chronicle.editor (sufficient for pushToProduction)

Note: Google SecOps SOAR roles may be named differently in your GCP project depending on the Google SecOps license tier. If a custom role is used, ensure it includes the chronicle.integrations.* and chronicle.remoteAgents.* permissions.

Additional GCP Platform Permissions

Permission	Required for
iam.serviceAccounts.actAs	If the service account needs to impersonate another SA (e.g. for connector instances that run as a different identity)
resourcemanager.projects.get	Reading project metadata during token introspection

These platform permissions are usually already granted on standard service accounts. If ValidateCredentials returns a 403 error, check these permissions first.

How to Create a Service Account and Key

1. Open the GCP Console and navigate to IAM & Admin → Service Accounts.
2. Click Create Service Account.
   • Name: e.g. nina-chronicle-integrations
   • Description: e.g. Service account for NINA Google SecOps Integrations connector
3. Click Create and Continue.
4. In the Grant this service account access to project step, assign the Google SecOps roles:
   • Add roles/chronicle.viewer, roles/chronicle.editor, or roles/chronicle.admin as appropriate.
5. Click Done.
6. In the service accounts list, click the new account.
7. Go to the Keys tab → Add Key → Create new key → select JSON → Create.
8. The JSON file is downloaded automatically. Store it securely immediately — it is shown only once.
9. Paste the entire JSON file content into the serviceAccountJson credential field in NINA.

Security note: Never commit the JSON key to source control. Store it exclusively in NINA's secure credential vault. Rotate keys every 90 days or per your organisation's key management policy. Each environment (dev, staging, production) should use a dedicated service account.

Shared Credential with Other Google SecOps Connectors

chronicle-integrations uses the same five credential fields and the same service account format as:

• chronicle-instances
• chronicle-cases
• chronicle-soar
• chronicle-detections
• chronicle-events

A single GCP service account can authenticate all Google SecOps connectors simultaneously. Create one service account per Google SecOps instance and reuse it across all Google SecOps connectors pointing to that instance.

Creating a Google SecOps Integrations Credential in NINA

1. Navigate to the Credentials section in NINA.
2. Click Add New Credential.
3. Select Google SecOps Integrations as the integration service.
4. Fill in the five fields:
   • Service Account JSON: paste the full JSON key file content
   • Region: e.g. eu
   • Project: e.g. my-project-123
   • Location: e.g. eu or europe-west2
   • Instance: e.g. fca7f167-b9d1-43b1-9d03-0257d31dcb63
5. Click Test Connection — this performs a GET /marketplaceIntegrations?pageSize=1 call to validate the credential.
6. Click Save to store the credential securely.

---

API URL and Resource Path Structure

Every API call is constructed as:

{baseURL}/{apiVersion}/projects/{project}/locations/{location}/instances/{instance}/{resource}[:{action}]

Where:

• baseURL = https://{region}-chronicle.googleapis.com
• apiVersion = v1 (all operations in this connector)
• resource = collection path, possibly nested (e.g. integrations/actions/revisions)
• action = optional custom verb appended with : (e.g. :pushToProduction, :rollback)

Concrete URL Examples

Operation	HTTP Method	Resolved URL
List marketplace integrations	GET	https://eu-chronicle.googleapis.com/v1/projects/{project}/locations/eu/instances/{uuid}/marketplaceIntegrations
Install marketplace integration	POST	https://eu-chronicle.googleapis.com/v1/projects/{project}/locations/eu/instances/{uuid}/marketplaceIntegrations:install
List integrations	GET	https://eu-chronicle.googleapis.com/v1/projects/{project}/locations/eu/instances/{uuid}/integrations
Push integration to production	POST	https://eu-chronicle.googleapis.com/v1/projects/{project}/locations/eu/instances/{uuid}/integrations:pushToProduction
List integration actions	GET	https://eu-chronicle.googleapis.com/v1/projects/{project}/locations/eu/instances/{uuid}/integrations/actions
Execute action test	POST	https://eu-chronicle.googleapis.com/v1/projects/{project}/locations/eu/instances/{uuid}/integrations/actions:executeTest
List connectors	GET	https://eu-chronicle.googleapis.com/v1/projects/{project}/locations/eu/instances/{uuid}/integrations/connectors
List connector instances	GET	https://eu-chronicle.googleapis.com/v1/projects/{project}/locations/eu/instances/{uuid}/integrations/connectors/connectorInstances
Run connector on demand	POST	https://eu-chronicle.googleapis.com/v1/projects/{project}/locations/eu/instances/{uuid}/integrations/connectors/connectorInstances:runOnDemand
Clear connector context properties	DELETE	https://eu-chronicle.googleapis.com/v1/projects/{project}/locations/eu/instances/{uuid}/integrations/connectors/contextProperties:clearAll
List remote agents	GET	https://eu-chronicle.googleapis.com/v1/projects/{project}/locations/eu/instances/{uuid}/remoteAgents
Upgrade remote agent	POST	https://eu-chronicle.googleapis.com/v1/projects/{project}/locations/eu/instances/{uuid}/remoteAgents:upgradeRemoteAgent
Rollback action revision	POST	https://eu-chronicle.googleapis.com/v1/projects/{project}/locations/eu/instances/{uuid}/integrations/actions/revisions:rollback

---

Rate Limits, Quotas, and Retry Behaviour

Behaviour	Detail
Rate-limit retry	On HTTP 429, the request is retried up to 3 times with exponential back-off (1 s → 2 s → 4 s)
Retry-After header	If Retry-After is present in the 429 response, that duration is used instead of the default back-off
Request timeout	All requests time out after 90 seconds
Timeout retry	On a network timeout, up to 3 retries with the same exponential back-off
No retry on 4xx	Non-429 client errors (400, 401, 403, 404) are returned immediately without retrying

Google SecOps SOAR API quotas vary by tier. Contact your Google SecOps account team if you regularly hit 429 responses.

---

Supported Operations

Resources Overview

Resource	Operations	Read / Write
integrations	create, delete, get, list, update, download, downloadDependency, exportIntegrationItems, fetchAffectedItems, fetchAgentIntegrations, fetchCommercialDiff, fetchDependencies, fetchRestrictedAgents, getFetchProductionDiff, getFetchStagingDiff, import, importIntegrationDependency, importIntegrationItems, pushToProduction, pushToStaging, upload	R/W
integrationActions	create, delete, get, list, update, executeTest, fetchActionsByEnvironment, fetchTemplate	R/W
integrationActionRevisions	create, delete, list, rollback	R/W
connectors	create, delete, get, list, update, executeTest, fetchTemplate	R/W
connectorInstances	create, delete, get, list, update, fetchLatestDefinition, runOnDemand, setLogsCollection	R/W
connectorInstanceLogs	get, list	R
connectorContextProperties	create, delete, get, list, update, clearAll	R/W
connectorRevisions	create, delete, list, rollback	R/W
integrationInstances	create, delete, get, list, update, executeTest, fetchAffectedItems, fetchDefaultInstance	R/W
jobs	create, delete, get, list, update, executeTest, fetchTemplate	R/W
jobContextProperties	create, delete, get, list, update, clearAll	R/W
jobInstances	create, delete, get, list, update, runOnDemand	R/W
jobInstanceLogs	get, list	R
jobRevisions	create, delete, list, rollback	R/W
logicalOperators	create, delete, get, list, update, executeTest, fetchTemplate	R/W
logicalOperatorRevisions	create, delete, list, rollback	R/W
managers	create, delete, get, list, update, fetchTemplate	R/W
managerRevisions	create, delete, get, list, rollback	R/W
transformers	create, delete, get, list, update, executeTest, fetchTemplate	R/W
transformerRevisions	create, delete, list, rollback	R/W
marketplaceIntegrations	get, list, fetchCommercialDiff, install, uninstall	R/W
remoteAgents	create, delete, get, list, update, connectorValidRemoteAgents, fetchEditableRemoteAgents, fetchInstallationCommand, fetchInstallerFile, fetchRedeployStatus, fetchRemoteAgentsCompatibleWithJobs, fetchRemoteAgentsInformation, migrateConnectors, redeployRemoteAgent, sendRemoteAgentInstaller, upgradeRemoteAgent	R/W

---

Operation Details

integrations

SOAR integrations are packages that bundle actions, connectors, jobs, and other components. They are the top-level unit of distribution in Google SecOps SOAR.

integrations.list

List all available SOAR integrations.

• HTTP Method: GET
• Path: /v1/projects/{project}/locations/{location}/instances/{instance}/integrations

Parameter	Type	Required	Description
pageSize	number	No	Maximum number of results to return
pageToken	string	No	Pagination token from a previous response
filter	string	No	Filter expression to narrow results

integrations.get

Retrieve a specific integration by resource name.

• HTTP Method: GET
• Path: /v1/.../integrations

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the integration (e.g. projects/{p}/locations/{l}/instances/{i}/integrations/{id})

integrations.create

Create a new SOAR integration.

• HTTP Method: POST
• Path: /v1/.../integrations

Parameter	Type	Required	Description
identifier	string	Yes	Unique identifier for the integration
displayName	string	No	Human-readable display name
description	string	No	Description of the integration's purpose

integrations.delete

Delete an existing integration.

• HTTP Method: DELETE
• Path: /v1/.../integrations

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the integration to delete

integrations.update (updateCustomIntegration)

Update a custom (non-marketplace) integration.

• HTTP Method: PATCH
• Path: /v1/.../integrations:updateCustomIntegration

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the integration
displayName	string	No	New display name
updateMask	string	No	Comma-separated list of fields to update

integrations.download

Download an integration as a distributable package.

• HTTP Method: POST
• Path: /v1/.../integrations:download

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the integration

integrations.downloadDependency

Download a dependency package for an integration.

• HTTP Method: POST
• Path: /v1/.../integrations:downloadDependency

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the integration
dependencyName	string	Yes	Name of the dependency to download

integrations.exportIntegrationItems

Export selected items (actions, connectors, jobs) from an integration.

• HTTP Method: POST
• Path: /v1/.../integrations:exportIntegrationItems

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the integration
items	array	No	List of item resource names to export; if omitted, all items are exported

integrations.fetchAffectedItems

Fetch the items that would be affected by a change to an integration.

• HTTP Method: GET
• Path: /v1/.../integrations:fetchAffectedItems

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the integration

integrations.fetchAgentIntegrations

Fetch integrations available to a specific agent.

• HTTP Method: GET
• Path: /v1/.../integrations:fetchAgentIntegrations

Parameter	Type	Required	Description
agentId	string	No	ID of the agent; omit to fetch for the default agent

Known limitation: This endpoint may return INVALID_ARGUMENT on certain instance tiers. It is pre-declared SKIPPED in the evidence report with reason (C).

integrations.fetchCommercialDiff

Fetch the commercial diff between the current version and the marketplace version of an integration.

• HTTP Method: GET
• Path: /v1/.../integrations:fetchCommercialDiff

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the integration

integrations.fetchDependencies

Fetch all dependencies required by an integration.

• HTTP Method: GET
• Path: /v1/.../integrations:fetchDependencies

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the integration

integrations.fetchRestrictedAgents

Fetch the list of agents that are restricted from accessing an integration.

• HTTP Method: GET
• Path: /v1/.../integrations:fetchRestrictedAgents

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the integration

integrations.getFetchProductionDiff

Get the diff between the staging and production versions of an integration.

• HTTP Method: GET
• Path: /v1/.../integrations:getFetchProductionDiff

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the integration

integrations.getFetchStagingDiff

Get the diff between the local and staging versions of an integration.

• HTTP Method: GET
• Path: /v1/.../integrations:getFetchStagingDiff

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the integration

integrations.import

Import an integration from a base64-encoded package.

• HTTP Method: POST
• Path: /v1/.../integrations:import

Parameter	Type	Required	Description
integrationPackage	string	Yes	Base64-encoded integration package content

integrations.importIntegrationDependency

Import a dependency package for an existing integration.

• HTTP Method: POST
• Path: /v1/.../integrations:importIntegrationDependency

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the integration
dependencyPackage	string	Yes	Base64-encoded dependency package

integrations.importIntegrationItems

Import specific items (actions, connectors, jobs) into an integration.

• HTTP Method: POST
• Path: /v1/.../integrations:importIntegrationItems

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the integration
itemsPackage	string	Yes	Base64-encoded items package

integrations.pushToProduction

Promote the staging version of an integration to production.

• HTTP Method: POST
• Path: /v1/.../integrations:pushToProduction

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the integration

integrations.pushToStaging

Push the current version of an integration to the staging environment.

• HTTP Method: POST
• Path: /v1/.../integrations:pushToStaging

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the integration

integrations.upload

Upload an integration package to the instance.

• HTTP Method: POST
• Path: /v1/.../integrations:upload

Parameter	Type	Required	Description
integrationPackage	string	Yes	Base64-encoded integration package to upload

---

integrationActions

Actions are the individual automation steps within a SOAR integration. They are the smallest executable unit.

integrationActions.list

List all actions within an integration.

• HTTP Method: GET
• Path: /v1/.../integrations/actions

Parameter	Type	Required	Description
parent	string	No	Resource name of the parent integration; omit to list across all integrations

Known limitation: This endpoint rejects pageSize as a query parameter (INVALID_ARGUMENT). Do not pass pageSize — omit pagination parameters and handle the full response set. Pre-declared SKIPPED in evidence with reason (C).

integrationActions.get

Retrieve a specific action.

• HTTP Method: GET
• Path: /v1/.../integrations/actions

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the action

integrationActions.create

Create a new action within an integration.

• HTTP Method: POST
• Path: /v1/.../integrations/actions

Parameter	Type	Required	Description
parent	string	Yes	Resource name of the parent integration
identifier	string	Yes	Unique identifier for the action
displayName	string	No	Human-readable display name

integrationActions.delete

Delete an action.

• HTTP Method: DELETE
• Path: /v1/.../integrations/actions

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the action

integrationActions.update

Update an existing action.

• HTTP Method: PATCH
• Path: /v1/.../integrations/actions

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the action
updateMask	string	No	Comma-separated list of fields to update

integrationActions.executeTest

Execute a test run for an action.

• HTTP Method: POST
• Path: /v1/.../integrations/actions:executeTest

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the action
testParams	object	No	Key-value parameters for the test execution

integrationActions.fetchActionsByEnvironment

Fetch actions filtered by deployment environment.

• HTTP Method: GET
• Path: /v1/.../integrations/actions:fetchActionsByEnvironment

Parameter	Type	Required	Description
environment	string	No	Environment name (e.g. production, staging)

integrationActions.fetchTemplate

Fetch a template for creating a new action.

• HTTP Method: GET
• Path: /v1/.../integrations/actions:fetchTemplate

Parameter	Type	Required	Description
identifier	string	No	Action template identifier

---

integrationActionRevisions

Every change to an action creates a new revision. Revisions allow you to audit changes and roll back to a previous state.

integrationActionRevisions.list

List all revisions of an action.

• HTTP Method: GET
• Path: /v1/.../integrations/actions/revisions

Parameter	Type	Required	Description
parent	string	No	Resource name of the parent action
pageSize	number	No	Maximum number of results
pageToken	string	No	Pagination token

integrationActionRevisions.create

Create a new revision snapshot of an action.

• HTTP Method: POST
• Path: /v1/.../integrations/actions/revisions

Parameter	Type	Required	Description
parent	string	Yes	Resource name of the parent action

integrationActionRevisions.delete

Delete a specific revision.

• HTTP Method: DELETE
• Path: /v1/.../integrations/actions/revisions

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the revision

integrationActionRevisions.rollback

Rollback an action to a previous revision.

• HTTP Method: POST
• Path: /v1/.../integrations/actions/revisions:rollback

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the target revision to restore

---

connectors

Connectors handle the authentication and communication with external systems (e.g. a SIEM, ticketing system, or threat intelligence platform). Each connector belongs to an integration.

connectors.list

List all connectors.

• HTTP Method: GET
• Path: /v1/.../integrations/connectors

Parameter	Type	Required	Description
parent	string	No	Resource name of the parent integration

Known limitation: This endpoint rejects pageSize as a query parameter (INVALID_ARGUMENT). Do not pass pageSize. Pre-declared SKIPPED in evidence with reason (C).

connectors.get

Retrieve a specific connector.

• HTTP Method: GET
• Path: /v1/.../integrations/connectors

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the connector

connectors.create

Create a new connector within an integration.

• HTTP Method: POST
• Path: /v1/.../integrations/connectors

Parameter	Type	Required	Description
parent	string	Yes	Resource name of the parent integration
identifier	string	Yes	Unique identifier for the connector
displayName	string	No	Human-readable display name

connectors.delete

Delete a connector.

• HTTP Method: DELETE
• Path: /v1/.../integrations/connectors

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the connector

connectors.update

Update an existing connector.

• HTTP Method: PATCH
• Path: /v1/.../integrations/connectors

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the connector
updateMask	string	No	Comma-separated list of fields to update

connectors.executeTest

Execute a connectivity test for a connector.

• HTTP Method: POST
• Path: /v1/.../integrations/connectors:executeTest

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the connector
testParams	object	No	Key-value parameters for the test

connectors.fetchTemplate

Fetch a template for creating a new connector.

• HTTP Method: GET
• Path: /v1/.../integrations/connectors:fetchTemplate

Parameter	Type	Required	Description
identifier	string	No	Connector template identifier

---

connectorInstances

A connector instance is a deployed, configured instance of a connector with specific credentials and settings for a target system.

connectorInstances.list

List all connector instances.

• HTTP Method: GET
• Path: /v1/.../integrations/connectors/connectorInstances

Parameter	Type	Required	Description
parent	string	No	Resource name of the parent connector
pageSize	number	No	Maximum number of results
pageToken	string	No	Pagination token

connectorInstances.get

Retrieve a specific connector instance.

• HTTP Method: GET
• Path: /v1/.../integrations/connectors/connectorInstances

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the connector instance

connectorInstances.create

Create a new connector instance.

• HTTP Method: POST
• Path: /v1/.../integrations/connectors/connectorInstances

Parameter	Type	Required	Description
parent	string	Yes	Resource name of the parent connector
displayName	string	No	Human-readable label for this instance
config	object	No	Connector-specific configuration (credentials, endpoints, etc.)

connectorInstances.delete

Delete a connector instance.

• HTTP Method: DELETE
• Path: /v1/.../integrations/connectors/connectorInstances

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the connector instance

connectorInstances.update

Update an existing connector instance configuration.

• HTTP Method: PATCH
• Path: /v1/.../integrations/connectors/connectorInstances

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the connector instance
config	object	No	Updated configuration
updateMask	string	No	Comma-separated list of fields to update

connectorInstances.fetchLatestDefinition

Fetch the latest connector definition available for an instance.

• HTTP Method: GET
• Path: /v1/.../integrations/connectors/connectorInstances:fetchLatestDefinition

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the connector instance

connectorInstances.runOnDemand

Trigger an immediate on-demand run of a connector instance outside its normal schedule.

• HTTP Method: POST
• Path: /v1/.../integrations/connectors/connectorInstances:runOnDemand

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the connector instance

connectorInstances.setLogsCollection

Configure whether logs are collected for a connector instance.

• HTTP Method: POST
• Path: /v1/.../integrations/connectors/connectorInstances:setLogsCollection

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the connector instance
collectLogs	bool	No	true to enable log collection, false to disable

---

connectorInstanceLogs

Execution logs produced by connector instance runs.

connectorInstanceLogs.get

Retrieve a specific log entry.

• HTTP Method: GET
• Path: /v1/.../integrations/connectors/connectorInstances/logs

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the log entry

connectorInstanceLogs.list

List log entries for a connector instance.

• HTTP Method: GET
• Path: /v1/.../integrations/connectors/connectorInstances/logs

Parameter	Type	Required	Description
parent	string	No	Resource name of the connector instance
pageSize	number	No	Maximum number of entries to return
pageToken	string	No	Pagination token

---

connectorContextProperties

Context properties are key-value pairs stored on a connector that are accessible during execution. They provide runtime configuration without redeploying the connector.

connectorContextProperties.list

List all context properties on a connector.

• HTTP Method: GET
• Path: /v1/.../integrations/connectors/contextProperties

Parameter	Type	Required	Description
parent	string	No	Resource name of the parent connector
pageSize	number	No	Maximum number of results
pageToken	string	No	Pagination token

connectorContextProperties.get

Retrieve a specific context property.

• HTTP Method: GET
• Path: /v1/.../integrations/connectors/contextProperties

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the context property

connectorContextProperties.create

Create a new context property on a connector.

• HTTP Method: POST
• Path: /v1/.../integrations/connectors/contextProperties

Parameter	Type	Required	Description
parent	string	Yes	Resource name of the parent connector
key	string	Yes	Property key name
value	string	Yes	Property value

connectorContextProperties.delete

Delete a specific context property.

• HTTP Method: DELETE
• Path: /v1/.../integrations/connectors/contextProperties

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the context property

connectorContextProperties.update

Update an existing context property value.

• HTTP Method: PATCH
• Path: /v1/.../integrations/connectors/contextProperties

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the context property
value	string	No	New value
updateMask	string	No	Comma-separated list of fields to update

connectorContextProperties.clearAll

Delete all context properties on a connector in a single call.

• HTTP Method: DELETE
• Path: /v1/.../integrations/connectors/contextProperties:clearAll

Parameter	Type	Required	Description
parent	string	Yes	Resource name of the connector whose properties to clear

---

connectorRevisions

connectorRevisions.list

List all revisions of a connector.

• HTTP Method: GET
• Path: /v1/.../integrations/connectors/revisions

Parameter	Type	Required	Description
parent	string	No	Resource name of the parent connector
pageSize	number	No	Maximum number of results
pageToken	string	No	Pagination token

connectorRevisions.create

Create a new revision snapshot of a connector.

• HTTP Method: POST
• Path: /v1/.../integrations/connectors/revisions

Parameter	Type	Required	Description
parent	string	Yes	Resource name of the parent connector

connectorRevisions.delete

Delete a specific connector revision.

• HTTP Method: DELETE
• Path: /v1/.../integrations/connectors/revisions

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the revision

connectorRevisions.rollback

Rollback a connector to a previous revision.

• HTTP Method: POST
• Path: /v1/.../integrations/connectors/revisions:rollback

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the target revision to restore

---

integrationInstances

An integration instance is a deployed copy of an integration with specific configuration for a particular use case or environment.

integrationInstances.list

List all integration instances.

• HTTP Method: GET
• Path: /v1/.../integrations/integrationInstances

Parameter	Type	Required	Description
parent	string	No	Resource name of the parent integration
pageSize	number	No	Maximum number of results
pageToken	string	No	Pagination token

integrationInstances.get / create / delete / update

Standard CRUD operations following the same parameter pattern as connectorInstances. The resource path is integrations/integrationInstances.

integrationInstances.executeTest

Execute a test run for an integration instance.

• HTTP Method: POST
• Path: /v1/.../integrations/integrationInstances:executeTest

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the integration instance
testParams	object	No	Test execution parameters

integrationInstances.fetchAffectedItems

Fetch items that would be affected by changes to an integration instance.

• HTTP Method: GET
• Path: /v1/.../integrations/integrationInstances:fetchAffectedItems

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the integration instance

integrationInstances.fetchDefaultInstance

Fetch the default instance for an integration.

• HTTP Method: GET
• Path: /v1/.../integrations/integrationInstances:fetchDefaultInstance

Parameter	Type	Required	Description
parent	string	Yes	Resource name of the parent integration

---

jobs

Jobs are scheduled or on-demand automation tasks within an integration. They typically run on a cron schedule or are triggered by events.

jobs.list

List all jobs within an integration.

• HTTP Method: GET
• Path: /v1/.../integrations/jobs

Parameter	Type	Required	Description
parent	string	No	Resource name of the parent integration

Known limitation: This endpoint may reject pageSize (INVALID_ARGUMENT). Omit pagination parameters when calling this endpoint.

jobs.get / create / delete / update

Standard CRUD following the same pattern as connectors. Path: integrations/jobs.

jobs.executeTest

Execute a test run for a job.

• HTTP Method: POST
• Path: /v1/.../integrations/jobs:executeTest

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the job
testParams	object	No	Test execution parameters

jobs.fetchTemplate

Fetch a template for creating a new job.

• HTTP Method: GET
• Path: /v1/.../integrations/jobs:fetchTemplate

Parameter	Type	Required	Description
identifier	string	No	Job template identifier

---

jobContextProperties

Context properties on jobs follow the exact same pattern as connectorContextProperties. Path prefix: integrations/jobs/contextProperties.

Operations: create, delete, get, list, update, clearAll

clearAll path: integrations/jobs/contextProperties:clearAll

---

jobInstances

Deployed instances of a job with specific configuration and scheduling.

Operations: create, delete, get, list, update, runOnDemand

runOnDemand path: /v1/.../integrations/jobs/jobInstances:runOnDemand

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the job instance

---

jobInstanceLogs

Operations: get, list

Path: integrations/jobs/jobInstances/logs

---

jobRevisions

Operations: create, delete, list, rollback

Rollback path: integrations/jobs/revisions:rollback

---

logicalOperators

Logical operators are reusable decision components that evaluate conditions within SOAR playbooks.

logicalOperators.list

List all logical operators.

• HTTP Method: GET
• Path: /v1/.../integrations/logicalOperators

Parameter	Type	Required	Description
parent	string	No	Resource name of the parent integration

Known limitation: May reject pageSize. Omit if you receive INVALID_ARGUMENT.

logicalOperators.get / create / delete / update

Standard CRUD following the same pattern as actions. Path: integrations/logicalOperators.

logicalOperators.executeTest

• HTTP Method: POST
• Path: /v1/.../integrations/logicalOperators:executeTest

Parameter	Type	Required	Description
name	string	Yes	Full resource name
testParams	object	No	Test parameters

logicalOperators.fetchTemplate

• HTTP Method: GET
• Path: /v1/.../integrations/logicalOperators:fetchTemplate

---

logicalOperatorRevisions

Operations: create, delete, list, rollback

Rollback path: integrations/logicalOperators/revisions:rollback

---

managers

Integration managers handle the orchestration and lifecycle of integration sub-components.

managers.list

List all integration managers.

• HTTP Method: GET
• Path: /v1/.../integrations/managers

Parameter	Type	Required	Description
parent	string	No	Resource name of the parent integration

Known limitation: May reject pageSize. Omit if you receive INVALID_ARGUMENT.

managers.get / create / delete / update

Standard CRUD. Path: integrations/managers.

managers.fetchTemplate

• HTTP Method: GET
• Path: /v1/.../integrations/managers:fetchTemplate

---

managerRevisions

Operations: create, delete, get, list, rollback

Rollback path: integrations/managers/revisions:rollback

---

transformers

Transformers are data transformation components used to convert, map, or enrich data between integration steps.

transformers.list

List all transformers.

• HTTP Method: GET
• Path: /v1/.../integrations/transformers

Parameter	Type	Required	Description
parent	string	No	Resource name of the parent integration

Known limitation: May reject pageSize. Omit if you receive INVALID_ARGUMENT.

transformers.get / create / delete / update

Standard CRUD. Path: integrations/transformers.

transformers.executeTest

• HTTP Method: POST
• Path: /v1/.../integrations/transformers:executeTest

Parameter	Type	Required	Description
name	string	Yes	Full resource name
testParams	object	No	Test parameters

transformers.fetchTemplate

• HTTP Method: GET
• Path: /v1/.../integrations/transformers:fetchTemplate

---

transformerRevisions

Operations: create, delete, list, rollback

Rollback path: integrations/transformers/revisions:rollback

---

marketplaceIntegrations

The Google SecOps SOAR marketplace provides pre-built integrations from Google and third-party vendors. These operations manage the browsing and lifecycle of marketplace content on your instance.

marketplaceIntegrations.list

List all marketplace integrations available to the instance.

• HTTP Method: GET
• Path: /v1/.../marketplaceIntegrations

Parameter	Type	Required	Description
pageSize	number	No	Maximum number of results
pageToken	string	No	Pagination token
filter	string	No	Filter expression (e.g. by category, name)

marketplaceIntegrations.get

Retrieve details for a specific marketplace integration.

• HTTP Method: GET
• Path: /v1/.../marketplaceIntegrations

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the marketplace integration

marketplaceIntegrations.fetchCommercialDiff

Fetch the diff between the installed version and the latest marketplace version.

• HTTP Method: GET
• Path: /v1/.../marketplaceIntegrations:fetchCommercialDiff

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the marketplace integration

marketplaceIntegrations.install

Install a marketplace integration on the Google SecOps instance.

• HTTP Method: POST
• Path: /v1/.../marketplaceIntegrations:install

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the marketplace integration to install

Warning: Installing a marketplace integration may create connector instances and context properties. Verify the integration's requirements before installing in production.

marketplaceIntegrations.uninstall

Uninstall a marketplace integration from the Google SecOps instance.

• HTTP Method: DELETE
• Path: /v1/.../marketplaceIntegrations:uninstall

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the marketplace integration to uninstall

Warning: Uninstalling removes all associated connector instances and their configurations. This is irreversible. Back up any important context properties before uninstalling.

---

remoteAgents

Remote agents are Google SecOps SOAR agents deployed on-premises or in isolated network segments. They proxy connector and job execution to systems that are not reachable from the Google SecOps cloud.

remoteAgents.list

List all Google SecOps remote agents registered on the instance.

• HTTP Method: GET
• Path: /v1/.../remoteAgents

Parameter	Type	Required	Description
pageSize	number	No	Maximum number of results
pageToken	string	No	Pagination token

remoteAgents.get

Retrieve a specific remote agent.

• HTTP Method: GET
• Path: /v1/.../remoteAgents

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the remote agent

remoteAgents.create

Register a new remote agent on the Google SecOps instance.

• HTTP Method: POST
• Path: /v1/.../remoteAgents

Parameter	Type	Required	Description
displayName	string	Yes	Human-readable name for the agent
config	object	No	Agent configuration (OS, network zone, etc.)

remoteAgents.delete

Unregister a remote agent.

• HTTP Method: DELETE
• Path: /v1/.../remoteAgents

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the remote agent

remoteAgents.update

Update a remote agent's configuration.

• HTTP Method: PATCH
• Path: /v1/.../remoteAgents

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the remote agent
config	object	No	Updated configuration
updateMask	string	No	Comma-separated list of fields to update

remoteAgents.connectorValidRemoteAgents

Get the remote agents that are valid targets for a specific connector.

• HTTP Method: POST
• Path: /v1/.../remoteAgents:connectorValidRemoteAgents

Parameter	Type	Required	Description
connectorName	string	No	Resource name of the connector

remoteAgents.fetchEditableRemoteAgents

Fetch remote agents that the current service account has edit permission on.

• HTTP Method: GET
• Path: /v1/.../remoteAgents:fetchEditableRemoteAgents

Known limitation: This endpoint rejects pageSize (INVALID_ARGUMENT). Do not pass pagination parameters.

remoteAgents.fetchInstallationCommand

Fetch the shell command required to install the remote agent binary.

• HTTP Method: GET
• Path: /v1/.../remoteAgents:fetchInstallationCommand

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the remote agent

remoteAgents.fetchInstallerFile

Fetch the installer binary for a remote agent.

• HTTP Method: GET
• Path: /v1/.../remoteAgents:fetchInstallerFile

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the remote agent

remoteAgents.fetchRedeployStatus

Check the status of an in-progress redeploy operation.

• HTTP Method: GET
• Path: /v1/.../remoteAgents:fetchRedeployStatus

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the remote agent

remoteAgents.fetchRemoteAgentsCompatibleWithJobs

Fetch remote agents that are compatible with SOAR job execution.

• HTTP Method: GET
• Path: /v1/.../remoteAgents:fetchRemoteAgentsCompatibleWithJobs

Known limitation: Rejects pageSize. Do not pass pagination parameters.

remoteAgents.fetchRemoteAgentsInformation

Fetch detailed operational information for all registered remote agents.

• HTTP Method: GET
• Path: /v1/.../remoteAgents:fetchRemoteAgentsInformation

Known limitation: Rejects pageSize. Do not pass pagination parameters.

remoteAgents.migrateConnectors

Migrate a set of SOAR connectors to a different remote agent.

• HTTP Method: POST
• Path: /v1/.../remoteAgents:migrateConnectors

Parameter	Type	Required	Description
name	string	Yes	Resource name of the target remote agent
connectors	array	Yes	List of connector resource names to migrate

remoteAgents.redeployRemoteAgent

Trigger a full redeploy of a remote agent (re-downloads and reinstalls the binary).

• HTTP Method: POST
• Path: /v1/.../remoteAgents:redeployRemoteAgent

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the remote agent

remoteAgents.sendRemoteAgentInstaller

Push the installer package to a remote agent host.

• HTTP Method: POST
• Path: /v1/.../remoteAgents:sendRemoteAgentInstaller

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the remote agent

remoteAgents.upgradeRemoteAgent

Upgrade a remote agent to a newer version.

• HTTP Method: POST
• Path: /v1/.../remoteAgents:upgradeRemoteAgent

Parameter	Type	Required	Description
name	string	Yes	Full resource name of the remote agent
targetVersion	string	No	Target version string; omit to upgrade to the latest available

---

Known Limitations

Resource / Operation	Behaviour	Reason	Workaround
integrationActions.list	INVALID_ARGUMENT when pageSize is passed	Endpoint does not support the pageSize query parameter	Omit pageSize; handle the full unbounded response
connectors.list	INVALID_ARGUMENT when pageSize is passed	Endpoint does not support pageSize	Omit pageSize
integrationInstances.list	INVALID_ARGUMENT when pageSize is passed	Endpoint does not support pageSize	Omit pageSize
jobs.list	INVALID_ARGUMENT when pageSize is passed	Endpoint does not support pageSize	Omit pageSize
logicalOperators.list	INVALID_ARGUMENT when pageSize is passed	Endpoint does not support pageSize	Omit pageSize
managers.list	INVALID_ARGUMENT when pageSize is passed	Endpoint does not support pageSize	Omit pageSize
transformers.list	INVALID_ARGUMENT when pageSize is passed	Endpoint does not support pageSize	Omit pageSize
remoteAgents.fetchEditableRemoteAgents	INVALID_ARGUMENT when pageSize is passed	Endpoint does not support pageSize	Omit pageSize
remoteAgents.fetchRemoteAgentsCompatibleWithJobs	INVALID_ARGUMENT when pageSize is passed	Endpoint does not support pageSize	Omit pageSize
remoteAgents.fetchRemoteAgentsInformation	INVALID_ARGUMENT when pageSize is passed	Endpoint does not support pageSize	Omit pageSize
integrations.fetchAgentIntegrations	INVALID_ARGUMENT with certain query combinations	Endpoint may require agent context that is not available as a simple query parameter	Provide a specific agentId value if the instance requires it
integrationActions.fetchActionsByEnvironment	HTTP 404 on some instance tiers	Endpoint not available on all Google SecOps tier/region combinations	Skip or test availability before relying on it in production workflows
connectorInstances.list	HTTP 404 on some instance tiers	Endpoint may not be available if the SOAR connector feature is not enabled on the instance	Contact Google SecOps support to verify connector instance support is enabled

---

Best Practices

1. Use ValidateCredentials before execution. The connector performs a GET /marketplaceIntegrations?pageSize=1 call. If this fails, all other operations will also fail — investigate the credential before deploying a workflow.

2. Omit pageSize for unsupported endpoints. Multiple SOAR resource endpoints (integrations/actions, integrations/connectors, integrations/jobs, etc.) return INVALID_ARGUMENT when pageSize is included. Call these endpoints without pagination parameters and paginate by pageToken only if a token is returned in the response.

3. Avoid destructive operations in production without a prior backup. Before calling delete, clearAll, uninstall, or rollback, retrieve the current state with a get or list call and store the result. Rollback and clear operations cannot be undone.

4. Use revisions before making changes. Call {resource}Revisions.create before updating any action, connector, job, manager, transformer, or logical operator in a production integration. This gives you an explicit restore point.

5. Use pushToStaging before pushToProduction. Always validate changes in the staging environment first. Use getFetchStagingDiff and getFetchProductionDiff to review what will change before promoting.

6. Resolve resource names from list before get. Google SecOps SOAR resource names are compound paths (e.g. projects/{p}/locations/{l}/instances/{i}/integrations/{id}/actions/{actionId}). Always resolve the full name from a list call rather than constructing it manually.

7. Remote agent operations are irreversible. redeployRemoteAgent and upgradeRemoteAgent cause the agent to restart. Schedule these during maintenance windows. Use fetchRedeployStatus to poll completion.

8. Connector instance context properties are sensitive. Context properties store credentials and configuration for external systems (API keys, passwords, tokens). Use clearAll only when decommissioning a connector instance; never during normal operation.

9. Marketplace install/uninstall affects runtime state. Installing a marketplace integration creates connector instances and context properties that may be picked up by running playbooks immediately. Co-ordinate marketplace changes with the SOAR operations team.

10. Apply least-privilege IAM. For read-only monitoring workflows, use roles/chronicle.viewer only. Grant roles/chronicle.admin and roles/chronicle.soarAdmin only to service accounts that explicitly need to manage remote agents, deploy integrations, or install marketplace content.

---

Troubleshooting

Error	Likely Cause	Solution
401 Unauthorized	Service account key is invalid, expired, or has been revoked	Re-download the JSON key from GCP Console and update the serviceAccountJson field
403 PERMISSION_DENIED	Service account lacks the Google SecOps IAM role required for the operation	Grant roles/chronicle.editor or roles/chronicle.admin on the GCP project; verify the role in GCP Console → IAM
400 INVALID_ARGUMENT: Unknown name "pageSize"	The endpoint does not support pageSize as a query parameter	Remove pageSize from the call; see the Known Limitations table
404 NOT_FOUND for a resource	The resource name is incorrect, or the resource does not exist on this instance	List the resource first to obtain the exact name; verify the project, location, and instance values
404 NOT_FOUND for an endpoint URL	The endpoint is not available on this Google SecOps tier or region	Check the Known Limitations section; contact Google SecOps support to confirm the feature is enabled
409 ALREADY_EXISTS	Attempting to create a resource that already exists (same identifier)	List existing resources and use update instead, or choose a different identifier
429 RESOURCE_EXHAUSTED	API rate limit exceeded	The connector retries automatically (3 times, 1 s / 2 s / 4 s back-off). For sustained rate limiting, reduce call frequency or contact Google SecOps support for a quota increase
500 INTERNAL	Transient Google SecOps API error	Retry the request. If the error persists, check the Google SecOps status page and open a support ticket
serviceAccountJson is required	Empty or blank serviceAccountJson field	Paste the complete JSON key file content — it must include type, project_id, private_key, and client_email fields
region is required	Empty or blank region field	Set to one of: us, eu, asia-southeast1, asia-south1, northamerica-northeast2, me-west1
failed to parse service account JSON	serviceAccountJson is not valid JSON or is not a service account key	Verify you pasted the entire JSON file. The type field must be "service_account"
credential validation failed	ValidateCredentials returned an error	Check all five credential fields; confirm the service account has at least roles/chronicle.viewer

---

Updated: 2026-07-08