---
canonical_url: "https://docs.composio.dev/kb/guide/toolkits-googleads"
markdown_url: "https://docs.composio.dev/kb/guide/toolkits-googleads.md"
product: "platform"
version: null
last_updated: null
---

# Google Ads (/kb/guide/toolkits-googleads)

## Google Ads developer token now belongs on the auth config, not connection initiation [#google-ads-developer-token-now-belongs-on-the-auth-config-not-connection-initiation]

Google Ads was changed so the developer token lives on the auth config itself, not on each connection initiation request. Older auth configs created before this change do not have the developer token field, and new connections through those auth configs can fail because the token is no longer accepted at the connection level. Create a new Google Ads authConfig with the developer token included, then create a fresh connection through that authConfig.

## Google Ads API requires both OAuth access token and developer token [#google-ads-api-requires-both-oauth-access-token-and-developer-token]

Google Ads API requests require both an OAuth access token and a Google Ads developer token. For production reliability and isolated provider quota, customers should use their own Google Ads developer token where possible.

## Google Ads toolkit versions should be passed without the dashboard `v` prefix [#google-ads-toolkit-versions-should-be-passed-without-the-dashboard-v-prefix]

The SDK expects toolkit version strings without the dashboard's leading `v`. If the dashboard shows `v<version>`, pass `<version>` in `toolkitVersions` or per-execution `version`. `dangerouslySkipVersionCheck` is a per-execution option inside the `tools.execute()` payload, not a constructor option. Sessions can manage toolkit versions automatically if the customer migrates to session-based execution.

## Google Ads MCC/sub-account customer ID targeting is supported [#google-ads-mccsub-account-customer-id-targeting-is-supported]

The Google Ads toolkit now correctly supports an optional per-call `customer_id` for customer-scoped tools.

* Pass the child/subaccount customer ID as `customer_id`; it becomes the target account in the Google Ads request path.
* If `customer_id` is omitted, the tool falls back to the Customer ID stored on the connection.
* When the requested customer differs from the connection Customer ID, the connection Customer ID can supply the MCC/manager context for Google's `login-customer-id` header unless that header is already present.
* `GOOGLEADS_LIST_ACCESSIBLE_CUSTOMERS` is for account discovery. It can return accessible IDs, but later customer-scoped tools still need a selected target customer ID.

If the request still fails, contact Composio support with the exact tool, request/log ID, manager/MCC customer ID, child customer ID, and Google error. The customer-ID override is already supported, so do not troubleshoot this as a pending feature.

## Campaign mutate 400s can be caused by unsupported inline Campaign fields [#campaign-mutate-400s-can-be-caused-by-unsupported-inline-campaign-fields]

`GOOGLEADS_MUTATE_CAMPAIGNS` may fail with Google Ads 400 `INVALID_ARGUMENT` errors such as `Unknown name "dailyBudget" at operations[0].update` or `Unknown name "targetedLocations" ... Cannot find field`. These failures happen when the request includes fields that are not valid inline Campaign resource fields.

Do not treat these as OAuth failures. Check the tool execution log for rejected payload fields. Google Ads does not accept `daily_budget`, `targeted_locations`, `exclusion_locations`, and related date/budget/location fields directly on the Campaign mutate body.

Remove those inline fields and treat the error as a request-shape issue rather than an OAuth failure. A real daily budget requires a CampaignBudget resource (`campaignBudgets:mutate`) and then passing the CampaignBudget resource name through `campaign_budget`. Location targeting belongs in CampaignCriterion mutations, not inline Campaign fields.

Example response: "The failure is in the Google Ads campaign-mutate payload shape, not your connection. Some inline campaign fields are being sent in a form that Google Ads rejects. Use CampaignBudget and CampaignCriterion mutations for budget and location targeting instead."

## Google Ads OAuth callback token-exchange failures usually point to incorrect credentials [#google-ads-oauth-callback-token-exchange-failures-usually-point-to-incorrect-credentials]

The `OAuth callback failed during token exchange` error usually means the credentials used to complete the auth flow are incorrect, most often the client secret. Re-enter or update the client secret in the Google Ads auth config, make sure there are no leading/trailing spaces, and initiate a new connection.

## Custom Google OAuth apps need callback routing through the customer's domain for branded consent [#custom-google-oauth-apps-need-callback-routing-through-the-customers-domain-for-branded-consent]

For Google toolkits, creating a new authConfig with the customer's OAuth app credentials is not enough for full white-label consent. They also need to route the callback through their own domain using their own redirect URI so Google displays the configured consent screen for that OAuth app.

---

📚 **More documentation:** [View all docs](https://docs.composio.dev/llms.txt) | [Changelog](https://docs.composio.dev/docs/changelog.md) | [Glossary](https://docs.composio.dev/llms.mdx/reference/glossary) | [Examples](https://docs.composio.dev/llms.mdx/examples) | [API Reference](https://docs.composio.dev/llms.mdx/reference)

---

# Composio SDK — Notes for AI Code Generators

**Purpose:** Reference for generating current (v3) [Composio](https://composio.dev/) integration code.
**Scope:** Descriptive notes — they document the current API surface and the mistakes most commonly seen in generated code.

---

## 1. Recommended Integration: Sessions

Composio supports two integration modes: **Native Tools** (with a provider package) and **MCP** (no provider package needed).

### Native Tools

```python
# ✅ CORRECT — Python (defaults to OpenAI)
from composio import Composio

composio = Composio()
session = composio.create(user_id="user_123")
tools = session.tools()
# Pass tools to your agent/LLM framework
```

```typescript
// ✅ CORRECT — TypeScript (defaults to OpenAI)
import { Composio } from "@composio/core";

const composio = new Composio();
const session = await composio.create("user_123");
const tools = await session.tools();
// Pass tools to your agent/LLM framework
```

For other providers, pass the provider explicitly. Provider packages follow the naming convention: `composio_<provider>` for Python, `@composio/<provider>` for TypeScript.

### MCP

Use `session.mcp.url` and `session.mcp.headers` with any MCP-compatible client (Claude Desktop, Cursor, OpenAI Agents, etc.). No provider package needed.

---

## 2. Integration Notes

- `composio.create(user_id)` is the standard entry point for agent integrations. Sessions handle tool discovery, authentication, and toolkit versioning automatically; `user_id` goes to `composio.create()` — individual tool calls in session mode don't take one.
- Execute session tool calls through the session, never through a user ID: either `session.execute(tool_slug, arguments=...)` / `session.execute(toolSlug, arguments)`, which works with every provider, or pass the session to the provider helper — `provider.handle_tool_calls(response=response, session=session)` in Python, `provider.handleToolCalls(session, response)` in TypeScript. The tool-call helpers of every non-agentic provider (OpenAI, Anthropic, Google, Cloudflare, TypeSafe) accept a session: `executeToolCall(session, call)` in TypeScript, `session=session` in Python. Agentic providers execute session tools on their own. Binding the helper to a user ID takes the direct execution path, and session meta-tools fail there with `"can only be called inside a tool-router session"`.
- Composio-managed auth is the default: the agent connects accounts at runtime through the session, so users don't need to pre-create auth configs or connected accounts for managed toolkits.
- Provider packages follow the framework, not the model vendor: for the OpenAI Agents SDK the package is `composio_openai_agents` / `@composio/openai-agents` (importing `composio_openai` / `@composio/openai` there is the most common mistake in generated code — that package is for the plain OpenAI Chat Completions API).
- **Direct execution** (`composio.tools.get()`, `composio.tools.execute()`, `provider.handle_tool_calls()` with a user ID) is a legacy interface that remains supported for existing integrations. Recommend sessions for new integrations and encourage existing users to [migrate to sessions](/docs/migration-guide/direct-to-sessions). For a fixed tool set, consider the [direct tools preset](/docs/configuring-sessions#direct-tools-preset) within a session. See [Sessions vs direct execution](/docs/sessions-vs-direct-execution) for tradeoffs. Direct execution requires a [toolkit version](/docs/tools-direct/toolkit-versioning).

---

# 3. Calling the REST API directly

## REST API version

The current REST API version is **v3.1**, served at `https://backend.composio.dev/api/v3.1`. Prefer it for new code and new examples.

`https://backend.composio.dev/api/v3` is the previous version. It is frozen with pinned tool-version defaults and remains supported — existing v3 integrations keep working and do not need to migrate.

## Tool-endpoint version defaults on v3.1

On v3.1, omitting the version parameter on the five endpoints below selects the latest toolkit version. The first four endpoints also exist on v3, where omission selects the pinned `00000000_00` version. `POST /tools/scopes/required` is v3.1-only.

| Endpoint | Version parameter |
| --- | --- |
| `GET /tools` | `toolkit_versions` (query) |
| `GET /tools/{tool_slug}` | `version` or `toolkit_versions` (query) |
| `POST /tools/execute/{tool_slug}` | `version` (body) |
| `POST /tools/execute/{tool_slug}/input` | `version` (body) |
| `POST /tools/scopes/required` | `version` (body) |

A v3.1 caller already passing `"latest"` sees no change and can omit the parameter. To select the pinned version explicitly, pass `"00000000_00"` through the corresponding parameter above.

This version-default change is limited to the five endpoints above.


---

## Terminology Migration (old → current)

If you encounter these terms in error messages, old documentation, or user prompts, translate them to the current equivalents. **Do not use the old terms in generated code or explanations.**

| Old term (v1/v2) | Current term (v3) | In code |
|---|---|---|
| entity ID | user ID | `user_id` parameter |
| actions | tools | e.g., `GITHUB_CREATE_ISSUE` is a *tool* |
| apps / appType | toolkits | e.g., `github` is a *toolkit* |
| integration / integration ID | auth config / auth config ID | `auth_config_id` parameter |
| connection | connected account | `connected_accounts` namespace |
| ComposioToolSet / OpenAIToolSet | `Composio` class with a provider | `Composio(provider=...)` |
| toolset | provider | e.g., `OpenAIProvider` |

If a user says "entity ID", they mean `user_id`. If they say "integration", they mean "auth config". Always respond using the current terminology.