# Migrating from initiate() to link() (/docs/auth-configuration/migrating-initiate-to-link) `composio.connected_accounts.initiate()` (Python) and `composio.connectedAccounts.initiate()` (TypeScript) wrap `POST /api/v3/connected_accounts`. That endpoint is being retired for **Composio-managed auth configs on redirectable OAuth schemes** (OAuth1, OAuth2, DCR\_OAUTH): * **2026-05-08, 00:00 UTC** — organizations created on or after this date are blocked. * **2026-07-03, 00:00 UTC** — all remaining organizations are blocked. After your org's cutover, calling `initiate()` for the affected combination raises `ComposioLegacyConnectedAccountsEndpointRetiredError` (TS) / `composio.exceptions.ComposioLegacyConnectedAccountsEndpointRetiredError` (Python). The replacement is `link()` — same return shape, same `redirectUrl` / `redirect_url`, same `waitForConnection()` / `wait_for_connection()` helper. > **Who this affects:** developers using a Composio-managed (default) auth config on OAuth1, OAuth2, or DCR\_OAUTH. If you brought your own OAuth client credentials (custom auth config) or use a non-OAuth scheme (API key, bearer, basic), your `initiate()` calls keep working — no migration needed. # Why When a connection is initiated through a default (Composio-managed) auth config, a Composio-owned OAuth application is acting on behalf of your integration. The end user should explicitly understand and acknowledge, at the moment of connection, that they are granting a third-party application access to their account on the external service. The `link()` flow enforces that consent step; the legacy `initiate()` path could bypass it when credentials were passed in directly. Concentrating Composio-managed OAuth on `link()` aligns the user experience with that consent guarantee. # Migration at a glance The signatures are the same shape — only the method name changes for the OAuth case. **Python:** **Before:** ```python connection_request = composio.connected_accounts.initiate( user_id="user_123", auth_config_id="ac_abc", ) print(connection_request.redirect_url) connected_account = connection_request.wait_for_connection() ``` **After:** ```python connection_request = composio.connected_accounts.link( user_id="user_123", auth_config_id="ac_abc", ) print(connection_request.redirect_url) connected_account = connection_request.wait_for_connection() ``` **TypeScript:** **Before:** ```typescript import { Composio } from '@composio/core'; const composio = new Composio({ apiKey: 'your_api_key' }); const connectionRequest = await composio.connectedAccounts.initiate( 'user_123', 'ac_abc' ); console.log(connectionRequest.redirectUrl); const connectedAccount = await connectionRequest.waitForConnection(); ``` **After:** ```typescript import { Composio } from '@composio/core'; const composio = new Composio({ apiKey: 'your_api_key' }); const connectionRequest = await composio.connectedAccounts.link( 'user_123', 'ac_abc' ); console.log(connectionRequest.redirectUrl); const connectedAccount = await connectionRequest.waitForConnection(); ``` `callback_url` / `callbackUrl` and `alias` work the same way on both methods. # What changes between the two methods | Concern | `initiate()` | `link()` | | --------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Underlying endpoint | `POST /api/v3/connected_accounts` | `POST /api/v3/connected_accounts/link` | | Return shape | `ConnectionRequest` with `id`, `redirect_url`, `wait_for_connection()` | Same | | `callback_url` / `callbackUrl` | ✓ | ✓ | | `alias` | ✓ | ✓ | | Pre-filled connection state (`config`) | ✓ — for non-OAuth schemes | Not needed — OAuth uses redirect; non-OAuth users keep `initiate()` | | `allow_multiple` / `allowMultiple` | ✓ — guards against duplicates | ✓ — same default (`False`), same exception ([since 2026-04-28](/docs/changelog/2026/04/28)) | | Affected by the 2026-05-08 / 2026-07-03 retirement (Composio-managed OAuth) | Yes | No | # How to know which auth config is which If you maintain a mix of Composio-managed and custom auth configs and aren't sure which path to take per call, look at the auth config record. The dashboard shows whether each config is "Default (Composio-managed)" or "Custom". Programmatically, the auth config retrieve response includes an `is_composio_managed` (Python) / `isComposioManaged` (TS) boolean. Route the call based on that field: **Python:** ```python auth_config = composio.auth_configs.get("ac_abc") if auth_config.is_composio_managed: request = composio.connected_accounts.link( user_id="user_123", auth_config_id="ac_abc", ) else: request = composio.connected_accounts.initiate( user_id="user_123", auth_config_id="ac_abc", ) ``` **TypeScript:** ```typescript import { Composio } from '@composio/core'; const composio = new Composio({ apiKey: 'your_api_key' }); const authConfig = await composio.authConfigs.get('ac_abc'); const request = authConfig.isComposioManaged ? await composio.connectedAccounts.link('user_123', 'ac_abc') : await composio.connectedAccounts.initiate('user_123', 'ac_abc'); ``` For most integrations the auth config is hard-coded per integration, so you'll know up front which path to use and can drop the branching. # Related * [Connected accounts → Multiple accounts](/docs/auth-configuration/connected-accounts#multiple-accounts) — using `link()` for multi-account flows * [Authenticating tools → Hosted Authentication](/docs/tools-direct/authenticating-tools#hosted-authentication-connect-link) — the canonical `link()` flow * [Changelog: Link Auth Migration](/docs/changelog/2026/04/24) — the announcement --- 📚 **More documentation:** [View all docs](https://docs.composio.dev/llms.txt) | [Glossary](https://docs.composio.dev/llms.mdx/docs/glossary) | [Cookbooks](https://docs.composio.dev/llms.mdx/cookbooks) | [API Reference](https://docs.composio.dev/llms.mdx/reference) --- # Composio SDK — Instructions for AI Code Generators **Purpose:** Enforce only the **current** and **correct** patterns for integrating [Composio](https://composio.dev/) tools into AI agents. **Scope:** All AI-generated code using Composio must follow these guardrails. --- ## 1. Correct Composio Integration 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_` for Python, `@composio/` 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. CRITICAL INSTRUCTIONS FOR AI MODELS ### 2.1 — ALWAYS DO THE FOLLOWING 1. **Use `composio.create(user_id)`** to create a session — this is the entry point for all Composio integrations. 2. **Use `session.tools()`** for native tool integration or **`session.mcp.url`** for MCP integration. 3. **Import** from the correct provider package (`composio_` for Python, `@composio/` for TypeScript). 4. **Pass `user_id` to `composio.create()`**, not to individual tool calls. ### 2.2 — NEVER DO THE FOLLOWING 1. **Do not** instruct users to manually create auth configs or connected accounts before running. 2. **Do not** import from `composio_openai` / `@composio/openai` when using OpenAI Agents SDK — use `composio_openai_agents` / `@composio/openai-agents` instead. ### 2.3 — DISCOURAGED (do not use unless user explicitly asks) Do **not** generate `composio.tools.get()`, `composio.tools.execute()`, or `composio.provider.handle_tool_calls()` unless the user explicitly requests direct tool execution. These are a supported but **not recommended** low-level interface. --- ## 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.