Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs(changelog): SEC-339 link auth migration for Composio-managed OAuth
Composioeb38c367b73d
diff --git a/docs/content/changelog/04-24-26-link-auth-migration.mdx b/docs/content/changelog/04-24-26-link-auth-migration.mdxnew file mode 100644index 000000000..c3c41ec5a--- /dev/null+++ b/docs/content/changelog/04-24-26-link-auth-migration.mdx@@ -0,0 +1,79 @@+---+title: "Link Auth Migration for Composio-Managed OAuth Connections"+description: "POST /api/v3/connected_accounts will stop creating Composio-managed OAuth1/OAuth2/DCR_OAUTH connections. Callers must migrate to POST /api/v3/connected_accounts/link. Rollout begins the first week of May 2026 for new organizations."+date: "2026-04-24"+---++`POST /api/v3/connected_accounts` is being retired for **Composio-managed OAuth connections**. New organizations begin migrating the first week of May 2026, and all remaining organizations follow the first week of July 2026. Once migrated, affected requests receive `400 BadRequest` with a message pointing at the replacement endpoint.++This does **not** affect custom auth configs (your own OAuth app) or non-OAuth schemes (API key, bearer token, basic auth, etc.) — those continue to work on `POST /api/v3/connected_accounts` unchanged. Only the specific combination of **Composio-managed auth config + redirectable OAuth scheme** (OAuth1, OAuth2, DCR_OAUTH) is moving.++<Callout type="warn">+**Breaking Change (phased rollout)**++If your integration calls `POST /api/v3/connected_accounts` for a Composio-managed OAuth1, OAuth2, or DCR_OAUTH auth config, it will start returning `400 BadRequest` on the dates below. Migrate to `POST /api/v3/connected_accounts/link` before your organization's cutover.++- **First week of May 2026** — organizations created on or after this window are blocked.+- **First week of July 2026** — all remaining organizations are blocked.+</Callout>++### What's Changing++| Request | Before | After (once rollout reaches your org) |+|---------|--------|-------------------------------------|+| `POST /api/v3/connected_accounts`, Composio-managed + OAuth1 / OAuth2 / DCR_OAUTH | Creates a connected account (redirect URL returned) | **`400 BadRequest`** — use `/link` instead |+| `POST /api/v3/connected_accounts`, custom auth config | Creates a connected account | Unchanged |+| `POST /api/v3/connected_accounts`, API key / bearer / other non-OAuth | Creates a connected account | Unchanged |+| `POST /api/v3/connected_accounts/link` | Creates a link session | Unchanged — the recommended path going forward |++### Why++The link endpoint is built to make it explicit to the end user that they are authorizing a third-party application, and it produces a consistent redirect URL for every redirectable scheme. Concentrating Composio-managed OAuth flows on `/link` removes the DX ambiguity of a single endpoint that either returns a redirect URL or creates a fully-initialized connection depending on inputs.++### Migration++**Before** — legacy create (will be rejected for Composio-managed OAuth):++```bash+curl -X POST https://backend.composio.dev/api/v3/connected_accounts \+ -H "Content-Type: application/json" \+ -H "x-api-key: ak_your_api_key" \+ -d '{+ "auth_config": { "id": "ac_your_composio_managed_oauth_config" },+ "connection": { "user_id": "your_end_user_id" }+ }'+```++**After** — link session (recommended, works for all schemes including non-OAuth and custom):++```bash+curl -X POST https://backend.composio.dev/api/v3/connected_accounts/link \+ -H "Content-Type: application/json" \+ -H "x-api-key: ak_your_api_key" \+ -d '{+ "auth_config_id": "ac_your_composio_managed_oauth_config",+ "user_id": "your_end_user_id"+ }'+```++The response contains a `redirect_url` (valid for 10 minutes) that the end user opens to authorize the integration, plus a `connected_account_id` you can use to poll for status or associate with your own records.++### Error Response (after rollout)++Requests that hit the retired combination receive:++```json+{+ "error": {+ "code": "BadRequest",+ "message": "Creating connections on this endpoint for Composio-managed OAuth auth configs is no longer supported. Use POST /api/v3/connected_accounts/link instead.",+ "suggestedFix": "Call POST /api/v3/connected_accounts/link with the same auth_config_id and user_id to get a redirect URL for the end user."+ }+}+```++### What to Do++- **If you use Composio-managed OAuth auth configs** (OAuth1, OAuth2, or DCR_OAUTH) via `POST /api/v3/connected_accounts`: switch to `POST /api/v3/connected_accounts/link` before your org's cutover date.+- **If you already use `/link`**: no action required.+- **If you use custom OAuth apps (your own `client_id` / `client_secret`) or non-OAuth auth (API key, bearer, etc.)**: no action required — the legacy endpoint continues to serve those cases.