Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs: separate webhook & event notification guides from triggers (#2606)
Sushmitha Mallesh5ecc56c4bb74
diff --cc docs/content/docs/tools-direct/authenticating-tools.mdxindex 44180dac8,6e2b8f473..2c7cdb372--- a/docs/content/docs/tools-direct/authenticating-tools.mdx+++ b/docs/content/docs/tools-direct/authenticating-tools.mdx@@@ -387,18 -387,18 +387,25 @@@ Learn how to [Manage connected accountsAfter creating a connection, it will have one of the following statuses that indicates its current state:--| Status | Description |--|--------|-------------|--| **ACTIVE** | Connection is established and working. You can execute tools with this connection. |--| **INACTIVE** | Connection is temporarily disabled. Re-enable it to use the connection again. |--| **PENDING** | Connection is being processed. Wait for it to become active. |--| **INITIATED** | Connection request has started but not yet completed. User may still need to complete authentication. |--| **EXPIRED** | Connection credentials have expired. Composio automatically attempts to refresh credentials before marking as expired. Re-authenticate to restore access. |--| **FAILED** | Connection attempt failed. Check error details and try creating a new connection. |++| Status | What it means | What to do |++|--------|---------------|------------|++| **ACTIVE** | Connection is working. Tools can be executed. | Nothing — you're good. |++| **INITIATED** | OAuth flow started but the user hasn't completed authentication yet. Auto-expires after 10 minutes. | Redirect the user to the Connect Link to finish authentication. |++| **EXPIRED** | Credentials are no longer valid and Composio cannot refresh them automatically. See [common causes](#why-connections-expire) below. | [Subscribe to expiry events](/docs/subscribing-to-connection-expiry-events) to detect this proactively. |++| **FAILED** | The authentication attempt did not succeed. Common causes: user denied consent during OAuth, invalid authorization code, or misconfigured auth config. | Check the `status_reason` field for details and retry the connection. |++| **INACTIVE** | Manually disabled via the API. The connection is preserved but cannot be used to execute tools. | Re-enable it via the API or dashboard to restore access. |--<Callout>- When credentials expire for OAuth connections, Composio automatically attempts to refresh them using the refresh token. The connection is only marked as **EXPIRED** after multiple refresh attempts have failed.-When credentials expire for OAuth connections, Composio automatically attempts to refresh them using the refresh token. The connection is only marked as **EXPIRED** after multiple refresh attempts have failed. Set up [connection expiry event notifications](/docs/subscribing-to-connection-expiry-events) to detect this proactively.--</Callout>++### Why connections expire++++Composio automatically refreshes OAuth tokens before they expire. A connection is only marked as **EXPIRED** after refresh attempts have failed. Common reasons:++++- **User revoked access** — The user went to the provider's settings (e.g., Google Account > Security > Third-party apps) and removed your app's access.++- **OAuth app deleted or disabled** — The OAuth application credentials were deleted or disabled in the provider's developer console.++- **Refresh token expired** — Some providers (e.g., Google with test/unverified apps) expire refresh tokens after a set period. Once expired, a new OAuth consent flow is required.++- **Provider-side revocation** — The provider revoked tokens due to policy changes, security events, or account-level restrictions.++- **Repeated transient failures** — If token refresh fails multiple times consecutively (e.g., due to prolonged provider outages), Composio marks the connection as expired after a threshold of failures.++++In all cases, the user must [re-authenticate](/docs/subscribing-to-connection-expiry-events#re-authenticate-the-user) to restore the connection. Check the `status_reason` field on the connected account for the specific reason. You can also [subscribe to connection expiry events](/docs/subscribing-to-connection-expiry-events) to detect this proactively.### Waiting for Connection Establishment