Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

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.mdx
new file mode 100644
index 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.