---

name: application-integration-basics metadata: version: "1.0.2" category: ApplicationDevelopment description: >- Explains Google Cloud Application Integration concepts, region provisioning, IAM roles, run-as service accounts, interface choices (REST, Python discovery client, Terraform, ADK), and platform limits. Use when setting up Application Integration in a Google Cloud project, enabling required APIs, provisioning a region, configuring IAM or run-as service accounts, choosing between Application Integration and custom code, or checking quotas and timeouts. Do not use for building, publishing, or invoking integrations (use application-integration-authoring) or diagnosing failed or stuck runs and logs (use application-integration-troubleshooting).

Application Integration Basics

Application Integration is Google Cloud's serverless, auto-scaling Integration-Platform-as-a-Service (iPaaS) for connecting Google Cloud services and third-party SaaS applications. It runs event-driven workflows made of triggers, tasks, data mappings, and Integration Connectors connections without requiring you to manage servers. Use this skill to decide whether Application Integration fits a workload, set up a project and region, configure IAM and run-as service accounts, choose the right API or tool interface, and design around platform limits.

Attribution

MUST READ: Before executing any gcloud command, REST API call, or Python discovery-client call, you MUST read Usage Attribution. For commands executed directly in the terminal (never in generated scripts, Terraform, ADK agents, or user code), prefix gcloud with CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:application-integration-basics)" and add agent-skills/1.0 (skill:application-integration-basics) to the User-Agent header of curl requests.

When to Use Application Integration vs. Custom Glue Code

| Choose Application Integration when... | Choose custom code (Cloud Run / Cloud Functions) when... | | :--- | :--- | | Connecting SaaS apps (CRM, ERP, databases, Google Cloud services) via prebuilt Integration Connectors. | You need sub-second latency or custom binary protocols. | | Orchestrating event-driven workflows from API, Pub/Sub, Cloud Scheduler, Salesforce, or Connector Event triggers. | Total workflow data exceeds 30 MB (or 8 MB for API trigger inputs and Connector payloads). | | Transforming JSON/array data visually with Data Mapping or Jsonnet without deploying containers. | Synchronous runs take longer than 2 minutes or asynchronous runs take longer than 10 minutes. | | Pausing workflows for human review (Approval or Suspend tasks up to 31 days). | You must call VPC-only HTTP endpoints directly without Private Service Connect connectors (Call REST Endpoint reaches the public internet only). | | Exposing enterprise workflows or connectors as tools to AI agents via ADK ApplicationIntegrationToolset. | You need arbitrary language packages or heavy in-memory compute beyond JavaScript (V8) or Jsonnet tasks. |

Safety and Confirmation Rules

• Read-only checks run freely: You may run gcloud services list, gcloud projects get-iam-policy, and HTTP GET calls to https://integrations.googleapis.com/v1/... or https://connectors.googleapis.com/v1/... without asking first.
• Require explicit user confirmation before any state change: Always show the exact command or request payload and wait for user approval before:
  • Enabling APIs (gcloud services enable).
  • Provisioning a region (clients:provision or terraform apply on google_integrations_client), especially with Customer-Managed Encryption Keys (CMEK), because enabling CMEK for a region cannot be undone.
  • Modifying IAM policies (gcloud projects add-iam-policy-binding or gcloud iam service-accounts add-iam-policy-binding).
  • Creating, uploading, publishing, unpublishing, executing, testing, or deleting any integration, version, auth profile, or connection.
• Never bundle destructive scripts that delete integrations, versions, auth profiles, or connections unattended.
• Host changes require approval. Before installing packages (pip install) or changing global gcloud or credential state (gcloud config set ... such as auth/impersonate_service_account, gcloud auth application-default login / set-quota-project), show the exact command and wait for the user's approval.

Choosing the Interface

Application Integration has no gcloud integrations command group (and no gcloud connectors command group), and no Google-managed remote MCP server. The REST API is the primary control and execution interface.

| Interface | What it covers | Authentication | | :--- | :--- | :--- | | REST API (curl) | Full v1 surface: region provisioning, integrations, versions, download/upload, publish, execute, schedule, executions, suspensions, authConfigs, templates. | Authorization: Bearer $(gcloud auth print-access-token) | | Python discovery client | Full v1 surface via googleapiclient.discovery.build("integrations", "v1") (and v2 via build("integrations", "v2"); no dedicated Cloud Client Library exists). Install with pip install "google-api-python-client>=2.100.0,<3" "google-auth>=2.20.0,<3" (changes host or credential state; get the user's approval first). | Application Default Credentials (gcloud auth application-default login) (changes host or credential state; get the user's approval first) | | Terraform (hashicorp/google) | Infrastructure only: google_integrations_client (region setup), google_integrations_auth_config, and google_integration_connectors_*. Does not manage integration workflow versions. | ADC or Terraform provider credentials | | ADK (ApplicationIntegrationToolset) | Exposes published API-trigger integrations or Integration Connectors actions/entities as tools for ADK agents (Python v0.1.0+, Java v0.3.0+). | ADC (gcloud auth application-default login) (changes host or credential state; get the user's approval first) or service account JSON | | Cloud console | Visual drag-and-drop editor, Quick/Advanced region setup, Approval task resolution, OAuth 2.0 authorization code consent flow. | Browser Google Cloud sign-in |

• Use gcloud only for generic Google Cloud tasks: enabling APIs (gcloud services enable), printing access tokens (gcloud auth print-access-token), managing IAM, and reading Cloud Logging (gcloud logging read).
• Integration Connectors includes an outbound MCP connector (MCP v1 and v2) that lets a workflow call an external MCP server as a connector target; this is an outbound connector, not a Google-managed MCP server for controlling Application Integration.
• Always use the global endpoint https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/... consistently for REST calls.
• Note on draft testing (integrations:test): Although POST .../integrations/INTEGRATION_NAME:test exists in the v1 REST API, its required TestIntegrationsRequest.clientId value is not publicly documented, so do not invent one; test integrations by publishing to a non-production project and calling :execute.
• See references/api-access.md for authentication setup, curl commands, Python discovery client patterns, and ADK ApplicationIntegrationToolset configuration.

Step-by-Step Region Setup Workflow

Application Integration is regional: confirm the target region is supported on Application Integration locations and use us-central1 as a well-supported default when the user has no preference. The region is the LOCATION in every REST path; no gcloud default-region setting applies to Application Integration. Provisioning is per region. Provisioning us-central1 does not provision europe-west1; repeat region provisioning for every LOCATION you use in PROJECT_ID. Ensure an active billing account is attached to PROJECT_ID before setup—an active billing account is required even when usage stays within the monthly free tier (see the Application Integration pricing page).

1. Check and enable required APIs

First check which APIs are already enabled (read-only):

gcloud services list --enabled --project=PROJECT_ID \
  --filter="config.name:(integrations.googleapis.com OR connectors.googleapis.com OR secretmanager.googleapis.com OR cloudkms.googleapis.com)"

After getting user confirmation, enable the required APIs (add cloudkms.googleapis.com only if configuring CMEK):

gcloud services enable \
  integrations.googleapis.com \
  connectors.googleapis.com \
  secretmanager.googleapis.com \
  --project=PROJECT_ID

2. Verify setup IAM roles on the caller

Setting up Application Integration requires roles/integrations.integrationAdmin, roles/connectors.admin, and roles/editor (plus roles/cloudkms.admin for CMEK). Check current bindings (read-only):

gcloud projects get-iam-policy PROJECT_ID --format=json

3. Provision the region (LOCATION)

Choose one of the three supported paths after getting user confirmation:

• Option A: REST (clients:provision)

  curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{}' \
    "https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/clients:provision"
  

  The response is {} when provisioning succeeds (clients:provision does not apply runAsServiceAccount; set the run-as identity on each integration version via IntegrationVersion.runAsServiceAccount). {} is also returned when the region is already provisioned; the call does not change an existing region's settings. Change HTTP calls or encryption on an existing region from the console's Regions page (when the region is already ACTIVE, cloudKmsConfig, enableHttpCall, and enableManagedAiFeatures on clients:provision are not applied). If PROJECT_ID was already registered through Apigee Integration, provisioning fails.

• Option B: Cloud console Open https://console.cloud.google.com/integrations, select LOCATION, and click Quick setup (enables the APIs, creates the default service account, and uses Google-managed encryption) or Advanced setup (to configure CMEK, HTTP calls, AI features, governance, or variable masking). To add another region later, go to Regions > Provision new region.

• Option C: Terraform (google_integrations_client) Use the google_integrations_client resource in hashicorp/google. Do not set run_as_service_account on google_integrations_client—that argument was removed in provider v8.0.0 (August 26, 2026), and it mapped to the clients:provision runAsServiceAccount field, which is likewise not applied; set the run-as identity on each integration version (IntegrationVersion.runAsServiceAccount) instead.

4. Sanity-check region access

Run a read-only list call against the region; a successful 200 OK response is a good sign that the API is reachable in LOCATION:

curl -sS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations"

See references/provisioning-and-terraform.md for all ProvisionClientRequest fields, CMEK and governance options, and complete Terraform examples.

Core Concepts at a Glance

• Integrations and Triggers: An integration is a workflow started by one or more triggers. Synchronous runs (SYNC) wait for completion and return output (integrations.execute, console test, sync Call Integration). Asynchronous runs (ASYNC) are fir