1
+---
2
+title: "Link Auth Migration for Composio-Managed OAuth Connections"
3
+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."
4
+date: "2026-04-24"
5
+---
6
+
7
+`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.
8
+
9
+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.
10
+
11
+<Callout type="warn">
12
+**Breaking Change (phased rollout)**
13
+
14
+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.
15
+
16
+- **First week of May 2026** — organizations created on or after this window are blocked.
17
+- **First week of July 2026** — all remaining organizations are blocked.
18
+</Callout>
19
+
20
+### What's Changing
21
+
22
+| Request | Before | After (once rollout reaches your org) |
23
+|---------|--------|-------------------------------------|
24
+| `POST /api/v3/connected_accounts`, Composio-managed + OAuth1 / OAuth2 / DCR_OAUTH | Creates a connected account (redirect URL returned) | **`400 BadRequest`** — use `/link` instead |
25
+| `POST /api/v3/connected_accounts`, custom auth config | Creates a connected account | Unchanged |
26
+| `POST /api/v3/connected_accounts`, API key / bearer / other non-OAuth | Creates a connected account | Unchanged |
27
+| `POST /api/v3/connected_accounts/link` | Creates a link session | Unchanged — the recommended path going forward |
28
+
29
+### Why
30
+
31
+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.
32
+
33
+### Migration
34
+
35
+**Before** — legacy create (will be rejected for Composio-managed OAuth):
36
+
37
+```bash
38
+curl -X POST https://backend.composio.dev/api/v3/connected_accounts \
39
+ -H "Content-Type: application/json" \
40
+ -H "x-api-key: ak_your_api_key" \
41
+ -d '{
42
+ "auth_config": { "id": "ac_your_composio_managed_oauth_config" },
43
+ "connection": { "user_id": "your_end_user_id" }
44
+ }'
45
+```
46
+
47
+**After** — link session (recommended, works for all schemes including non-OAuth and custom):
48
+
49
+```bash
50
+curl -X POST https://backend.composio.dev/api/v3/connected_accounts/link \
51
+ -H "Content-Type: application/json" \
52
+ -H "x-api-key: ak_your_api_key" \
53
+ -d '{
54
+ "auth_config_id": "ac_your_composio_managed_oauth_config",
55
+ "user_id": "your_end_user_id"
56
+ }'
57
+```
58
+
59
+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.
60
+
61
+### Error Response (after rollout)
62
+
63
+Requests that hit the retired combination receive:
64
+
65
+```json
66
+{
67
+ "error": {
68
+ "code": "BadRequest",
69
+ "message": "Creating connections on this endpoint for Composio-managed OAuth auth configs is no longer supported. Use POST /api/v3/connected_accounts/link instead.",
70
+ "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."
71
+ }
72
+}
73
+```
74
+
75
+### What to Do
76
+
77
+- **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.
78
+- **If you already use `/link`**: no action required.
79
+- **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.