We've reorganized our documentation navigation structure to align directly with your operational workflows. See the release notes and the walkthrough video 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.

For a quick overview of the migration process, watch the embedded video.

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, Cloud Identity, and Identity and Access Management (IAM). It also addresses many of the limitations and complexities of the legacy APIs.

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.

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 MCP, 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, you can no longer call legacy APIs (Backstory API and Ingestion API) from new instances.
By July 20, 2027, you must migrate all existing instances to the Chronicle API, as the legacy APIs will no longer be available.

Before you begin

Before migrating to the Chronicle API, make sure you complete the following:

Deploy on modern SIEM infrastructure: Make sure the instance is deployed on your or your MSSP partner's Google Cloud project leveraging the modern SIEM infrastructure. For detailed instructions, see SIEM migration overview.
Enable the Chronicle API: In the Google Cloud console, navigate to the project hosting your instance and enable the Chronicle API (chronicle.googleapis.com). For details, see Enabling an API in your Google Cloud project.

Migrate to the Chronicle API

Migrate your scripts and integrations from the legacy APIs to the Chronicle API by completing the following steps:

Audit API usage: Identify all scripts and integrations in your environment that invoke legacy endpoints.
Set up authentication and authorization: Configure your environment to authenticate and authorize requests to the Chronicle API.
Map endpoints and update URLs: Replace legacy endpoints with their modern regional equivalents.
Update API logic: Adjust your request payloads and response handling to match the modern API's data models.
Test your integration: Validate the changes in a staging environment before deploying to production.

Audit API usage

Audit your environment to identify scripts or integrations invoking backstory.googleapis.com or malachiteingestion-pa.googleapis.com. You can identify these integrations by reviewing your codebase, automation scripts, and third-party tools.

Set up authentication and authorization

Configure your environment to authenticate and authorize requests to the Chronicle API:

Choose an authentication method: Choose how your workloads authenticate to the Chronicle API using one of the listed methods. We recommend using Workload Identity Federation for better security, as it avoids managing and storing long-lived service account keys. For advanced authentication scenarios (such as service account impersonation), see Authenticate to the Chronicle API.
- Workload Identity Federation (recommended): Set up Workload Identity Federation to allow workloads running outside of Google Cloud to authenticate using external identities.
- Service Accounts: If you must use service accounts, create a service account in your Google Cloud project and generate and download a private key in JSON format. Keep this key secure.
Grant IAM permissions: Grant the required IAM permissions to the identity (either the service account or the external identity principal) used for authentication. Assign the required IAM roles to your identity depending on the required level of access. See Manage access to projects, folders, and organizations for details. Predefined roles include the following:
We recommend using the principle of least privilege to grant only the permissions needed for your 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.
Set the credentials environment variable: Configure your runtime environment to use the credentials with Application Default Credentials (ADC) by setting the GOOGLE_APPLICATION_CREDENTIALS environment variable. This variable should point to either the downloaded service account key JSON file or the Workload Identity Federation credential configuration file. The Google Cloud client libraries automatically detect this variable to authenticate requests:
```
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"
```
Update OAuth scopes: Update the scope string if your legacy integration scripts explicitly requested OAuth scopes for token generation. 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).

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

Update the base URL of your API calls to point to the correct regional service endpoint. The Chronicle API is a regional service, so you must call the regional service endpoint that matches the location of your Google SecOps instance.

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

Review the Chronicle API REST reference to identify and implement changes to field names and data structures in your application. While some legacy endpoints might remain similar, you must update your integrations to match the latest data models and endpoint structures.

Use Google Cloud client libraries

Simplify your integration to automatically handle authentication, token refreshing, and transport details. We recommend using the official Google Cloud client libraries for doing so. 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.

Troubleshoot

This section describes how to resolve common errors you might encounter during the migration.

HTTP 403 Forbidden or PERMISSION_DENIED

If your API calls return an HTTP 403 Forbidden or PERMISSION_DENIED error, verify the following:

Authentication method and principal: Ensure you are using the correct credentials.
- If using Workload Identity Federation, verify that the external identity principal matches the principal bound to the IAM roles in your project.
- If using a service account, verify that the correct service account is being used and that it has not been disabled. Don't use legacy service accounts (often containing bk or malachite-cx in their email address) for modern Chronicle API endpoints.
IAM roles: Check that the service account or external identity principal has been granted the required predefined or custom IAM roles (such as Chronicle API Viewer or Chronicle API Editor) in your Google Cloud project. For granular endpoint permissions, see SIEM API endpoint mapping.

HTTP 401 Unauthorized or UNAUTHENTICATED

If your API calls fail with HTTP 401 Unauthorized or UNAUTHENTICATED, check the following:

OAuth scopes: Verify that your scripts are requesting the modern scope: https://www.googleapis.com/auth/chronicle (or the broader https://www.googleapis.com/auth/cloud-platform scope). The legacy scope (https://www.googleapis.com/auth/chronicle-backstory) does not grant access to the modern Chronicle API.
Environment variable: Confirm that the GOOGLE_APPLICATION_CREDENTIALS environment variable is set and points to the correct JSON key file or Workload Identity Federation configuration file in your runtime environment.

HTTP 404 Not Found or regional mismatches

If your API calls return an HTTP 404 Not Found or fail to connect, check your regional endpoints:

Regional Endpoint: The Chronicle API is a regional service. Verify that you are calling the endpoint that matches the region of your Google SecOps instance (for example, https://europe-west3-chronicle.googleapis.com for an instance in Frankfurt). Sending requests to a different region will result in errors. For a full list of regional addresses, see Update the service endpoint or the official Service endpoint reference.

What's next

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