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: SEC-339 callouts on canonical authenticating-tools / connected-accounts pages

Composio32bd1c65b5bf
diff --git a/docs/content/docs/auth-configuration/connected-accounts.mdx b/docs/content/docs/auth-configuration/connected-accounts.mdx
index f45ceb23e..92f290805 100644
--- a/docs/content/docs/auth-configuration/connected-accounts.mdx
+++ b/docs/content/docs/auth-configuration/connected-accounts.mdx
@@ -259,8 +259,10 @@ Disabling masking exposes full credentials in API responses. Only disable this i
Users can connect multiple accounts for the same toolkit (e.g., personal and work Gmail).
-<Callout type="info">
-Use `link()` for creating accounts, as it provides hosted authentication and allows multiple accounts by default. See [Connect Link authentication](/docs/tools-direct/authenticating-tools#hosted-authentication-connect-link).
+<Callout type="warn">
+**For Composio-managed OAuth, prefer `link()`.** The `initiate()` examples below will stop working for Composio-managed OAuth auth configs starting **2026-05-08** (new orgs) / **2026-07-03** (all orgs). `link()` provides hosted authentication, allows multiple accounts by default, and is unaffected by the rollout. See [Connect Link authentication](/docs/tools-direct/authenticating-tools#hosted-authentication-connect-link), the [migration guide](/docs/auth-configuration/migrating-initiate-to-link), or the [changelog entry](/docs/changelog/2026/04/24).
+
+The `initiate()` examples remain accurate for **custom auth configs** (your own OAuth app) and **non-OAuth schemes** (API key, bearer, basic) — those are unaffected.
</Callout>
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
diff --git a/docs/content/docs/auth-configuration/custom-auth-configs.mdx b/docs/content/docs/auth-configuration/custom-auth-configs.mdx
index 4231f65ca..74cac71cd 100644
--- a/docs/content/docs/auth-configuration/custom-auth-configs.mdx
+++ b/docs/content/docs/auth-configuration/custom-auth-configs.mdx
@@ -98,6 +98,10 @@ Once you have the OAuth credentials, you can add them to the auth config in the
This auth config is now ready to be used in your application!
+<Callout type="info">
+The `initiate()` example below is **safe for custom auth configs**. The `initiate()` retirement announced in the [2026-04-24 changelog](/docs/changelog/2026/04/24) only affects **Composio-managed** auth configs on OAuth1 / OAuth2 / DCR_OAUTH — not the custom OAuth app you just configured here. Custom auth configs continue to work on `initiate()` indefinitely.
+</Callout>
+
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
<Tab value="Python">
```python
diff --git a/docs/content/docs/tools-direct/authenticating-tools.mdx b/docs/content/docs/tools-direct/authenticating-tools.mdx
index 052700164..4886ae752 100644
--- a/docs/content/docs/tools-direct/authenticating-tools.mdx
+++ b/docs/content/docs/tools-direct/authenticating-tools.mdx
@@ -183,6 +183,12 @@ https://your-app.com/callback?user_id=user_123&status=success&connected_account_
#### OAuth Connections
+<Callout type="warn">
+**`initiate()` is being retired for Composio-managed OAuth.** If your auth config is Composio-managed (the default — you didn't bring your own OAuth client credentials), `initiate()` will start returning `400 BadRequest` on **2026-05-08** for new organizations and **2026-07-03** for all remaining organizations. Use [Hosted Authentication (Connect Link)](#hosted-authentication-connect-link) above with `composio.connectedAccounts.link()` (TS) / `composio.connected_accounts.link()` (Python) instead — same return shape, same `redirectUrl` / `redirect_url` field, and it works for every redirectable scheme.
+
+Custom auth configs (your own OAuth app) and non-OAuth schemes (API key, bearer token, basic) continue to work on `initiate()` unchanged. See the [migration guide](/docs/auth-configuration/migrating-initiate-to-link) and the [changelog entry](/docs/changelog/2026/04/24).
+</Callout>
+
For OAuth flows, you'll redirect users to complete authorization. You can specify a callback URL to control where users return after authentication:
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>