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.

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/...

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.
Ask the user before installing packages (
```
pip install
```
) or changing global gcloud settings such as
```
gcloud config set auth/impersonate_service_account
```
; show the exact command first.

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"` .	Application Default Credentials ( `gcloud auth application-default login` )
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` ) 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):

bash

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):

bash

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):

bash

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
)
bash
```
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

bash

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 fire-and-forget (
```
integrations.schedule
```
, Schedule, Cloud Scheduler, Cloud Pub/Sub, Salesforce triggers, and runs resumed after a suspension or approval).

Tasks: Units of work chained after a trigger (such as

Data Mapping

Call REST Endpoint

Connectors

JavaScript

on V8,

Cloud Function

Approval

Suspend

Timer

, loops, and

Call Integration

Versions and Edit Locks: Only a
```
DRAFT
```
version can be edited (locked to its author for 15 minutes after the last update). Only an
```
ACTIVE
```
(published) version runs from triggers. Publishing a version automatically unpublishes the prior active version and cancels any suspended executions of that prior version. Unpublishing moves an active version to
```
SNAPSHOT
```
(
```
PREVIOUSLY_PUBLISHED
```
). Calling
```
versions.delete
```
soft-deletes a version into
```
ARCHIVED
```
(listed as
```
DELETED
```
on the Integration versions documentation page).
Variables:
- Integration variables: Explicit inputs (
```
IN
```
  ), outputs (
```
OUT
```
  ),
```
IN_OUT
```
  , or internal variables with
```
IN_OUT_TYPE_UNSPECIFIED
```
  (
```
$varName$
```
  ).
- Task variables: Auto-generated task outputs named
```
`Task_<taskId>_<variableName>`
```
  where
```
taskId
```
  is the bare task number in
```
taskConfigs[].taskId
```
  (for example,
```
taskId
```
```
"1"
```
  ->
```
$`Task_1_responseBody`$
```
  ).
- System variables: keys are backtick-wrapped (
```
`ExecutionId`
```
  ,
```
`ExecutionMode`
```
  ,
```
`ErrorInfo`
```
  [
```
message
```
  ,
```
code
```
  ],
```
`IntegrationName`
```
  ,
```
`Region`
```
  ,
```
`ProjectId`
```
  ); reference them as
```
$`ExecutionId`$
```
  (a bare
```
$ExecutionId$
```
  names a nonexistent integration variable and fails).
- Config variables (Preview): Environment-specific values defined in
```
integrationConfigParameters
```
  (with defaults in
```
parameter.defaultValue
```
  ; a top-level
```
value
```
  on a draft is discarded) and supplied per environment in
```
configParameters
```
  at publish time (named
```
`CONFIG_<NAME>`
```
  ; keys in
```
configParameters
```
  must exactly match a key in
```
integrationConfigParameters
```
  , backticks included, such as
```
"`CONFIG_target_url`"
```
  , because unknown keys are silently ignored—publish returns 200 and the default stays). Never store secrets in config variables—they are exported in plain text. Use an authentication profile (
```
authConfigs
```
  ) or the Secret Manager task instead.
Suspensions:
```
Suspend
```
tasks pause up to 31 days and are resumed via the Suspensions API (
```
suspensions:lift
```
, with an optional
```
suspensionResult
```
, requiring
```
integrations.suspensions.lift
```
).
```
Approval
```
tasks email approvers and can be approved or rejected in the Cloud console UI or via
```
suspensions:resolve
```
(
```
state
```
:
```
"LIFTED"
```
or
```
"REJECTED"
```
, requiring
```
integrations.suspensions.resolve
```
). Listing suspensions (
```
suspensions.list
```
) requires
```
integrations.suspensions.list
```
. All three permissions are included in
```
roles/integrations.suspensionResolver
```
(and
```
roles/integrations.integrationAdmin
```
), and resuming also requires
```
roles/iam.serviceAccountUser
```
on the integration's run-as service account; always confirm with the user before lifting or resolving.
```
Timer
```
tasks resume automatically.
Authentication Profiles (
authConfigs
): Reusable regional credential records (
```
projects/PROJECT_ID/locations/LOCATION/authConfigs/AUTH_CONFIG_ID
```
). They are not included when downloading an integration version.

See references/core-concepts.md for full details on version states, trigger types, task categories, variables, suspensions, and authentication profiles.

IAM and the Run-As Service Account Requirement

Key IAM roles and service agents

Developer & operator roles:

roles/integrations.integrationAdmin

(full CRUD + delete auth profiles),

roles/integrations.integrationEditor

(create/upload/edit/test/invoke/cancel/replay/publish, including

integrations.integrationVersions.create

and

integrations.integrationVersions.deploy

roles/integrations.integrationDeployer

(publish/unpublish via

integrations.integrationVersions.deploy

; holds

list

get

deploy

but not

create

, so it can publish an existing version but cannot upload),

roles/integrations.integrationInvoker

(invoke/cancel/replay),

roles/integrations.integrationViewer

(view integrations and logs), and

roles/integrations.suspensionResolver

(list, lift, and resolve suspensions:

integrations.suspensions.list

integrations.suspensions.lift

integrations.suspensions.resolve

;

suspensionResolver

alone cannot read execution records, so also grant

roles/integrations.integrationViewer

to inspect

taskExecutionDetails

or run

:troubleshoot

, or use the approval email link, which carries the execution and task IDs).

Service agents:

Application Integration service agent:

service-PROJECT_NUMBER@gcp-sa-integrations.iam.gserviceaccount.com

(granted

roles/integrations.serviceAgent

Integration Connectors service agent:

service-PROJECT_NUMBER@gcp-sa-connectors.iam.gserviceaccount.com

(granted

roles/connectors.serviceAgent

Mandatory run-as service account rules (effective October 15, 2026)

Explicit identity required: For integrations created on or after October 15, 2026 (and for existing integrations at a later date), every run needs an explicit identity—either the triggering caller or a user-managed run-as service account set per integration version via
```
IntegrationVersion.runAsServiceAccount
```
(region provisioning via
```
clients:provision
```
does not apply
```
runAsServiceAccount
```
).
Triggers other than API or Private require a run-as service account: Integrations created on or after October 15, 2026 with any trigger other than an API or Private trigger (for example Schedule, Cloud Scheduler, Cloud Pub/Sub, Eventarc, Salesforce, or Connector Event) cannot be tested or published unless
runAsServiceAccount
is set. Private triggers are exempt like API triggers, so a sub-integration whose only trigger is Private can be published without
```
runAsServiceAccount
```
.
Region governance: If governance is enabled on the region, a run-as service account is mandatory for every new integration and version, including API-trigger integrations.
Service Account User (
roles/iam.serviceAccountUser
): Whenever
```
runAsServiceAccount
```
is set on a version, the user (or principal) publishing or testing the version must hold
```
roles/iam.serviceAccountUser
```
on that service account (or its owning project). At runtime, the invoking caller or trigger service account—and anyone resolving or lifting a suspension—must also hold
```
roles/iam.serviceAccountUser
```
on it.
Best practice: Create one dedicated, minimally scoped user-managed service account per integration. When
```
runAsServiceAccount
```
is set and no task-level auth profile is set, it mints tokens for Connector, Call REST Endpoint, and Cloud Function tasks (an OAuth 2.0 or OIDC auth profile on a task takes precedence over
```
runAsServiceAccount
```
).

See references/iam-and-service-accounts.md for the complete IAM role tables, service agent permissions, credential precedence rules, and

gcloud

IAM commands.

Key Quotas and Limits to Design Around

Limit	Value	Design impact
SYNC execution timeout	2 minutes	Use async triggers or `integrations.schedule` for workflows exceeding 2 minutes; timed-out sync runs become `CANCELLED` .
ASYNC execution timeout	10 minutes	Split heavy work into sub-integrations or external jobs if a single async run exceeds 10 minutes.
Max execution lifetime	31 days	Includes time paused in `Approval` or `Suspend` tasks (max 44,640 minutes).
Total integration data	30 MB	Shared across input/output variables and private-trigger sub-integrations. Above 10 MB, local logging is disabled, retries stop working, and monitoring skips the run.
API trigger input size	8 MB	Cumulative size across all input variables; larger payloads fail before the workflow starts.
Connectors data & timeout	8 MB in/out; 3 min timeout	Application Integration quotas cap cumulative data sent to/from connections at 8 MB and connector response at 20 MB (Integration Connectors quotas cap the Connectors task payload at 10 MB); custom queries cap at 180 seconds and 50,000 rows.
Concurrent executions	50 per project per region; 10 per integration (defaults)	Both concurrency caps are adjustable; a burst on a single integration hits the 10-per-integration cap, not 50. The execution request rate quota is shown on the project's Cloud Quotas page and can be adjusted there.
Integrations / tasks / versions	1,000 / 100 / 100	Up to 1,000 integrations per project, 100 tasks per integration, and 100 versions per integration.
Publish propagation	Up to 10 minutes	Eventual consistency: an older version can keep running for up to 10 minutes after publishing a new version.

See references/limits.md for all task-specific payload caps, loop iteration limits, Integration Connectors node limits, and pricing details.

Sibling Skills

application-integration-basics (this skill): Concepts, API enablement, region provisioning, IAM roles and run-as service accounts, interface choices (REST, Python client, Terraform, ADK), and quotas/limits.
application-integration-authoring: Building, uploading, versioning, config variables, publishing, executing, and testing integrations via the REST API; trigger IDs; task gotchas; and CI/CD promotion across projects with download/upload.
application-integration-troubleshooting: Diagnosing failed or stuck executions, checking execution and task states and
```
ErrorInfo
```
, listing and filtering executions, Cloud Logging and Cloud Monitoring, suspensions and approvals, Integration Connectors connection health, and IAM / run-as / quota errors.

Reference Files

references/core-concepts.md: Triggers, execution modes, task types, version lifecycle, edit locks, variables, suspensions, and authentication profiles.
references/iam-and-service-accounts.md: Predefined IAM roles for Application Integration and Integration Connectors, service agents, run-as service account rules, and IAM commands.
references/provisioning-and-terraform.md: Per-region provisioning via REST
```
clients:provision
```
, Cloud console Quick/Advanced setup, CMEK caveats, and Terraform
```
google_integrations_*
```
/
```
google_integration_connectors_*
```
resources.
references/api-access.md: Endpoints, authentication,
```
curl
```
examples, Python
```
google-api-python-client
```
discovery patterns, ADK
```
ApplicationIntegrationToolset
```
, and MCP connector clarification.
references/limits.md: Timeouts, payload caps, concurrency quotas, loop/task limits, Integration Connectors limits, and pricing tiers.

application-integration-basics

NPX Install

Tags

SKILL.md Content

Application Integration Basics

When to Use Application Integration vs. Custom Glue Code

Safety and Confirmation Rules

Choosing the Interface

Step-by-Step Region Setup Workflow

1. Check and enable required APIs

2. Verify setup IAM roles on the caller

3. Provision the region (
`LOCATION`
)

4. Sanity-check region access

Core Concepts at a Glance

IAM and the Run-As Service Account Requirement

Key IAM roles and service agents

Mandatory run-as service account rules (effective October 15, 2026)

Key Quotas and Limits to Design Around

Sibling Skills

Reference Files

application-integration-basics

NPX Install

Tags

SKILL.md Content

Application Integration Basics

When to Use Application Integration vs. Custom Glue Code

Safety and Confirmation Rules

Choosing the Interface

Step-by-Step Region Setup Workflow

1. Check and enable required APIs

2. Verify setup IAM roles on the caller

3. Provision the region (LOCATION)

4. Sanity-check region access

Core Concepts at a Glance

IAM and the Run-As Service Account Requirement

Key IAM roles and service agents

Mandatory run-as service account rules (effective October 15, 2026)

Key Quotas and Limits to Design Around

Sibling Skills

Reference Files

3. Provision the region (
`LOCATION`
)