Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 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 Friday, May 8, 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 on **Friday, May 8, 2026**, and all remaining organizations follow on **Friday, July 3, 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 | - **Friday, May 8, 2026 (00:00 UTC)** — organizations created on or after this timestamp are blocked. |
| 17 | - **Friday, July 3, 2026 (00:00 UTC)** — 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 | When a connection is initiated through a default (Composio-managed) auth config, a Composio-owned OAuth application is acting on behalf of your integration. We want the end user to 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. That acknowledgement is enforced by the `/link` flow, which routes the user through a consent screen before the connection is created. The legacy `POST /api/v3/connected_accounts` path allowed that step to be bypassed when credentials were passed in directly, which this change closes. |
| 32 | |
| 33 | Custom auth configs are unaffected because they are backed by your own OAuth application — the consent screen is served by your app, so you already own that experience. This change is scoped specifically to default auth configs on redirectable schemes, where the third-party relationship is with Composio rather than with the developer. |
| 34 | |
| 35 | ### Migration |
| 36 | |
| 37 | **Before** — legacy create (will be rejected for Composio-managed OAuth): |
| 38 | |
| 39 | ```bash |
| 40 | curl -X POST https://backend.composio.dev/api/v3/connected_accounts \ |
| 41 | -H "Content-Type: application/json" \ |
| 42 | -H "x-api-key: <YOUR_API_KEY>" \ |
| 43 | -d '{ |
| 44 | "auth_config": { "id": "ac_your_composio_managed_oauth_config" }, |
| 45 | "connection": { "user_id": "your_end_user_id" } |
| 46 | }' |
| 47 | ``` |
| 48 | |
| 49 | **After** — link session (recommended, works for all schemes including non-OAuth and custom): |
| 50 | |
| 51 | ```bash |
| 52 | curl -X POST https://backend.composio.dev/api/v3/connected_accounts/link \ |
| 53 | -H "Content-Type: application/json" \ |
| 54 | -H "x-api-key: <YOUR_API_KEY>" \ |
| 55 | -d '{ |
| 56 | "auth_config_id": "ac_your_composio_managed_oauth_config", |
| 57 | "user_id": "your_end_user_id" |
| 58 | }' |
| 59 | ``` |
| 60 | |
| 61 | 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. |
| 62 | |
| 63 | ### Error Response (after rollout) |
| 64 | |
| 65 | Requests that hit the retired combination receive: |
| 66 | |
| 67 | ```json |
| 68 | { |
| 69 | "error": { |
| 70 | "code": "BadRequest", |
| 71 | "message": "Creating connections on this endpoint for Composio-managed OAuth auth configs is no longer supported. Use POST /api/v3/connected_accounts/link instead.", |
| 72 | "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." |
| 73 | } |
| 74 | } |
| 75 | ``` |
| 76 | |
| 77 | ### What to Do |
| 78 | |
| 79 | - **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 — **Friday, May 8, 2026** for organizations created on or after that date, **Friday, July 3, 2026** for all others. |
| 80 | - **If you already use `/link`**: no action required. |
| 81 | - **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. |