We've reorganized our navigation structure to align directly with your operational workflows. See the Google SecOps release notes for more information.

Migrate from legacy SIEM API to Chronicle API

Supported in:

Google secops SIEM

This document helps you manage applications that call any of the legacy SIEM APIs (Backstory API and Ingestion API). It describes the steps you must follow to set up programmatic access and update any references from the legacy SIEM API endpoints to the modern Chronicle API endpoints.

The Chronicle API surface introduces several improvements designed to streamline your development process and align with Google Cloud API standards for improved reliability, security, performance, and stronger integration with Cloud Audit Logs, Cloud Monitoring, and Cloud Identity and Identity and Access Management (IAM). It also addresses many of the limitations and complexities present in the older API.

What is changing

All programmatic requests to legacy Backstory API and Ingestion API endpoints must transition to the modern Chronicle API. If your organization uses custom integrations, automation scripts, or third-party tools that make calls to these legacy endpoints, you must update those workloads to use modern endpoints and authentication flows before July 20, 2027.

What is not changing

Actions performed directly in the Google SecOps user interface (UI) already invoke the modern Chronicle API. If your organization only interacts with Google SecOps through the UI, or if your integrations already call Chronicle API endpoints, you are not required to take any action.

Prerequisites

Before migrating to the Chronicle API, make sure your instance is deployed on your Google Cloud project leveraging the modern SIEM infrastructure. For detailed instructions, see SIEM migration overview.

Key changes and enhancements

The following table highlights the major differences between the legacy SIEM API and the Chronicle API:

Feature area	Legacy SIEM API	Chronicle API	Details
Credential management	Manual process involving Google representatives	Self-service management of service accounts, credentials, and IAM permissions	Self-service credential and IAM management simplify onboarding and remove dependence on manual support requests.
Compliance standards	Limited support	Built-in support for Data Residency controls, VPC Service Controls, Access Transparency, CMEK, and FedRAMP	Modern built-in infrastructure controls meet industry compliance and regulatory standards.
Logging and auditing	Legacy audit streams	Cloud Audit Logs integrated into your Google Cloud project	Direct integration provides centralized audit trails and monitoring.
Authentication	API token and service account credentials	OAuth 2.0 with support for modern authentication methods, including Workload Identity and service accounts as described in Authentication for Google Cloud APIs and services	These modern authentication methods provide enhanced security and standardize the credential flow.
Data models and API design	Flat, proprietary structures	Resource-oriented design, RESTful architecture, and standardized naming following AIPs	This modern design improves data consistency, makes the API more intuitive, and simplifies object manipulation.
Endpoint naming	Inconsistent	RESTful and standardized	Consistent naming makes the API more intuitive and easier to integrate.
Ecosystem	Very limited	Integration with OneMCP, Terraform, client libraries, and SDKs	Broad compatibility with modern cloud tooling and automation frameworks.

Deprecation schedule

The legacy SIEM API is scheduled to be shut down on July 20, 2027. We recommend completing your migration before this date to avoid any service interruptions:

Starting October 26, 2026, new instances can no longer call legacy APIs (Backstory API and Ingestion API).
If you have an existing instance, you have a window until July 20, 2027 to complete your migration to the Chronicle API.

Set up authentication and authorization

The Chronicle API uses standard Google Cloud IAM for secure access control. You must configure your environment to use Google Cloud credentials.

1. Configure the Google Cloud project

Enable the Chronicle API: In the Google Cloud console, navigate to your project and enable the Chronicle API (chronicle.googleapis.com). For details, see Enabling an API in your Google Cloud project.
Create a service account: Create a service account in your Google Cloud project to be used by your scripts or applications. For detailed instructions, see Create service accounts.
Grant IAM roles: Assign the required IAM roles to your user or automation service account depending on the required level of access (see Manage access to projects, folders, and organizations). Predefined roles include:
We recommend following the principle of least privilege to grant only the permissions needed for users or automations by leveraging custom or predefined IAM roles.

Note: See SIEM API endpoint mapping to find the specific granular IAM permissions required for the modern endpoints replacing your legacy calls.
Download the service account key: Generate and download a private key in JSON format for the service account. Keep this key secure. For detailed instructions, see Create and delete service account keys.

2. Set the credentials environment variable

Configure your runtime environment to use the downloaded key with Application Default Credentials (ADC) by setting the GOOGLE_APPLICATION_CREDENTIALS environment variable. The Google Cloud client libraries automatically detect this variable to authenticate requests:

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"

3. Update OAuth scopes

If your legacy integration scripts explicitly requested OAuth scopes for token generation, you must update the scope string. The legacy scope doesn't grant access to the modern API surface:

Legacy Backstory scope: https://www.googleapis.com/auth/chronicle-backstory
Chronicle scope: https://www.googleapis.com/auth/chronicle (or the broader https://www.googleapis.com/auth/cloud-platform scope).

For more advanced authentication scenarios (such as Workload Identity Federation for keyless authentication or service account impersonation), see Authenticate to the Chronicle API.

Map endpoints and update URLs

Familiarize yourself with the Chronicle API surface, map your legacy calls, and update the service endpoints in your application.

Review reference documentation

Familiarize yourself with the comprehensive documentation for the Chronicle API.

Map endpoints to the Chronicle API

Identify the corresponding modern endpoints for each of the legacy API calls your application makes. Similarly, map your existing data models to the modern structures, accounting for any schema changes or additional fields. For details across all SIEM endpoints, see SIEM API endpoint mapping. If your workflow also interacts with SOAR endpoints, see the SOAR API endpoint mapping table.

Update the service endpoint

A service endpoint is the base URL that specifies the network address of an API service. A single service can have multiple service endpoints. The Chronicle API is a regional service and only supports regional endpoints.

All modern endpoints use a consistent prefix, making the final endpoint address predictable. The following example shows the modern endpoint URL structure:

[api_version]/projects/[project_id]/locations/[location]/instances/[instance_id]/...

This structure makes the final address to the endpoint as follows:

https://[service_endpoint]/[api_version]/projects/[project_id]/locations/[location]/instances/[instance_id]/...

Where:

service_endpoint: A regional service address.
api_version: The API version to query. Can be v1alpha, v1beta, or v1.
project_id: Your project ID (same project as you defined for your IAM permissions).
location: The location of your project (region); same as the regional endpoints.
instance_id: Your Google Security Operations SIEM customer ID.

Regional addresses:

africa-south1: https://africa-south1-chronicle.googleapis.com or https://chronicle.africa-south1.rep.googleapis.com
asia-northeast1: https://asia-northeast1-chronicle.googleapis.com or https://chronicle.asia-northeast1.rep.googleapis.com
asia-south1: https://asia-south1-chronicle.googleapis.com or https://chronicle.asia-south1.rep.googleapis.com
asia-southeast1: https://asia-southeast1-chronicle.googleapis.com or https://chronicle.asia-southeast1.rep.googleapis.com
asia-southeast2: https://asia-southeast2-chronicle.googleapis.com or https://chronicle.asia-southeast2.rep.googleapis.com
australia-southeast1: https://australia-southeast1-chronicle.googleapis.com or https://chronicle.australia-southeast1.rep.googleapis.com
europe-west12: https://europe-west12-chronicle.googleapis.com or https://chronicle.europe-west12.rep.googleapis.com
europe-west2: https://europe-west2-chronicle.googleapis.com or https://chronicle.europe-west2.rep.googleapis.com
europe-west3: https://europe-west3-chronicle.googleapis.com or https://chronicle.europe-west3.rep.googleapis.com
europe-west6: https://europe-west6-chronicle.googleapis.com or https://chronicle.europe-west6.rep.googleapis.com
europe-west9: https://europe-west9-chronicle.googleapis.com or https://chronicle.europe-west9.rep.googleapis.com
me-central1: https://me-central1-chronicle.googleapis.com or https://chronicle.me-central1.rep.googleapis.com
me-central2: https://me-central2-chronicle.googleapis.com or https://chronicle.me-central2.rep.googleapis.com
me-west1: https://me-west1-chronicle.googleapis.com or https://chronicle.me-west1.rep.googleapis.com
northamerica-northeast2: https://northamerica-northeast2-chronicle.googleapis.com or https://chronicle.northamerica-northeast2.rep.googleapis.com
southamerica-east1: https://southamerica-east1-chronicle.googleapis.com or https://chronicle.southamerica-east1.rep.googleapis.com
United States (us): https://us-chronicle.googleapis.com or https://chronicle.us.rep.googleapis.com
Europe (eu): https://eu-chronicle.googleapis.com or https://chronicle.eu.rep.googleapis.com

For a comprehensive list of all supported endpoints, see the official reference in the Chronicle API Service endpoint documentation.

For example, to list all detection rules for an instance in the us location, send the following request:

GET 
  https://us-chronicle.googleapis.com/v1alpha/projects/my-project-name-or-id/locations/us/instances/408bfb7b-5746-4a50-885a-50a323023529/rules

Similarly, to query SOAR resources such as cases using the regional endpoint (rep) alias, send the following request:

GET 
  https://chronicle.us.rep.googleapis.com/v1alpha/projects/my-project-name-or-id/locations/us/instances/408bfb7b-5746-4a50-885a-50a323023529/cases

Update API logic

Analyze the modern data models and endpoint structures provided in the API reference. Not all methods have changed significantly, and some existing code can be reused. The primary objective is to review the latest reference documentation and, for each specific use case, identify and implement necessary changes to field names and data structures within your application's logic.

Use Google Cloud client libraries

To simplify your integration and automatically handle authentication, token refreshing, and transport details, we recommend using the official Google Cloud client libraries. Chronicle API support is available across eight programming languages, including Python, Go, Java, Node.js, and C#. For installation and usage details, see Client libraries and SDK.

Test your integration

Test your updated application in a staging integration before deploying to production:

Create a test plan: Define test cases that cover all migrated functionalities.
Execute tests: Run automated and manual tests to confirm accuracy and validity.
Monitor performance: Assess the performance of your application with the modern API.

Need more help? Get answers from Community members and Google SecOps professionals.