@devries-cameron20 / composio Mirror · read-only / commits / eb38c367b
Fork 0

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

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 23:30 UTC

docs(changelog): SEC-339 link auth migration for Composio-managed OAuth

Announce the phased retirement of POST /api/v3/connected_accounts for Composio-managed + redirectable-OAuth auth configs. New orgs begin the first week of May 2026; remaining orgs follow the first week of July 2026. Custom auth configs and non-OAuth schemes are unaffected. Covers migration to POST /api/v3/connected_accounts/link with before / after cURL examples and the error response that affected callers will see after rollout. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Composio committed Apr 24, 2026 at 14:37 UTC eb38c367b73d0476e21de5d552252f5166ba7698
1 file changed +79
docs/content/changelog/04-24-26-link-auth-migration.mdx new
+79
@@ -0,0 +1,79 @@
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.