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(sdk): document OAuth token auto-detection and status override behavior

jkomyno680ae0132882
diff --git a/python/composio/core/models/connected_accounts.py b/python/composio/core/models/connected_accounts.py
index a11b7daeb..7eb8fdeb5 100644
--- a/python/composio/core/models/connected_accounts.py
+++ b/python/composio/core/models/connected_accounts.py
@@ -93,6 +93,11 @@ class AuthScheme:
) -> connected_account_create_params.ConnectionState:
"""
Create a new connected account using OAuth 1.0.
+
+ When both ``oauth_token`` and ``oauth_token_secret`` are provided,
+ status defaults to ACTIVE (token import). When either is omitted,
+ status defaults to INITIALIZING (redirect-based OAuth flow).
+ Pass an explicit ``status`` in options to override.
"""
has_tokens = bool(
options.get("oauth_token") # type: ignore[union-attr]
@@ -116,6 +121,11 @@ class AuthScheme:
) -> connected_account_create_params.ConnectionState:
"""
Create a new connected account using OAuth 2.0.
+
+ When ``access_token`` is provided, status defaults to ACTIVE
+ (token import). When omitted, status defaults to INITIALIZING
+ (redirect-based OAuth flow). Pass an explicit ``status`` in
+ options to override.
"""
has_token = bool(options.get("access_token")) # type: ignore[union-attr]
status = "ACTIVE" if has_token else "INITIALIZING"
diff --git a/ts/packages/core/src/models/AuthScheme.ts b/ts/packages/core/src/models/AuthScheme.ts
index 9ee42abb8..ead3da04d 100644
--- a/ts/packages/core/src/models/AuthScheme.ts
+++ b/ts/packages/core/src/models/AuthScheme.ts
@@ -7,7 +7,10 @@ import {
export class AuthScheme {
/**
- * Creates a ConnectionData object for OAuth2 authentication
+ * Creates a ConnectionData object for OAuth2 authentication.
+ * When `access_token` is provided, status defaults to ACTIVE (token import).
+ * When omitted, status defaults to INITIALIZING (redirect-based OAuth flow).
+ * Pass an explicit `status` in params to override the auto-detected default.
* @param params The OAuth2 parameters
* @returns ConnectionData object
*/
@@ -44,7 +47,10 @@ export class AuthScheme {
}
/**
- * Creates a ConnectionData object for OAuth1 authentication
+ * Creates a ConnectionData object for OAuth1 authentication.
+ * When both `oauth_token` and `oauth_token_secret` are provided, status defaults to ACTIVE (token import).
+ * When either is omitted, status defaults to INITIALIZING (redirect-based OAuth flow).
+ * Pass an explicit `status` in params to override the auto-detected default.
* @param params The OAuth1 parameters
* @returns ConnectionData object
*/