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, 04:45 UTC
| 1 | --- |
| 2 | title: "ConnectedAccounts" |
| 3 | description: "Manage connected accounts. This class is used to manage connected accounts in the Composio SDK. These are used to authenticate with third-party se..." |
| 4 | --- |
| 5 | |
| 6 | ## Methods |
| 7 | |
| 8 | ### refresh() |
| 9 | |
| 10 | Refresh the credentials of a connected account. |
| 11 | |
| 12 | ```python |
| 13 | def refresh(nanoid: str, **params: Unpack[connected_account_refresh_params.ConnectedAccountRefreshParams]) -> connected_account_refresh_response.ConnectedAccountRefres... |
| 14 | ``` |
| 15 | |
| 16 | **Parameters** |
| 17 | |
| 18 | | Name | Type | Description | |
| 19 | |------|------|-------------| |
| 20 | | `nanoid` | `str` | The connected account ID (`ca_xxx`). | |
| 21 | | `params?` | `Unpack[connected_account_refresh_params.ConnectedAccountRefreshParams]` | | |
| 22 | |
| 23 | **Returns** |
| 24 | |
| 25 | `connected_account_refresh_response.ConnectedAccountRefres...` — The refresh response. |
| 26 | |
| 27 | **Example** |
| 28 | |
| 29 | ```python |
| 30 | composio.connected_accounts.refresh("ca_abc123") |
| 31 | ``` |
| 32 | |
| 33 | --- |
| 34 | |
| 35 | ### revoke() |
| 36 | |
| 37 | Revoke a connected account's upstream tokens (best effort) and mark the connection `REVOKED`. Raises `composio.exceptions.ComposioConnectedAccountRevocationNotSupportedError` when the toolkit does not support programmatic revocation (API 400) and `composio.exceptions.ComposioConnectedAccountNotRevokableError` when the connection is not in a revokable state (API 409). |
| 38 | |
| 39 | ```python |
| 40 | def revoke(nanoid: str) -> connected_account_revoke_response.ConnectedAccountRevokeR... |
| 41 | ``` |
| 42 | |
| 43 | **Parameters** |
| 44 | |
| 45 | | Name | Type | Description | |
| 46 | |------|------|-------------| |
| 47 | | `nanoid` | `str` | The connected account ID (`ca_xxx`). | |
| 48 | |
| 49 | **Returns** |
| 50 | |
| 51 | `connected_account_revoke_response.ConnectedAccountRevokeR...` — The revoked tokens and the updated connected account. |
| 52 | |
| 53 | **Example** |
| 54 | |
| 55 | ```python |
| 56 | result = composio.connected_accounts.revoke("ca_abc123") |
| 57 | print(result.connected_account.status) # "REVOKED" |
| 58 | ``` |
| 59 | |
| 60 | --- |
| 61 | |
| 62 | ### complete_auth() |
| 63 | |
| 64 | Complete a deferred OAuth connection once you have verified the user's identity. When your project has an OAuth callback verifier configured, Composio does not activate a new OAuth connection by itself: it redirects to your verifier with a single-use session URI. After confirming who the user is, redeem it here; Composio checks that your project owns the pending connection and that `user_id` is its owner, completes the token exchange, and the connection becomes `ACTIVE`. Redeeming a session twice, or after it expires, fails with a 404 from the API. |
| 65 | |
| 66 | ```python |
| 67 | def complete_auth(*, user_id: str, session_uri: str) -> connected_account_complete_auth_response.ConnectedAccount... |
| 68 | ``` |
| 69 | |
| 70 | **Parameters** |
| 71 | |
| 72 | | Name | Type | Description | |
| 73 | |------|------|-------------| |
| 74 | | `user_id` | `str` | The user the connection was initiated for. | |
| 75 | | `session_uri` | `str` | The session URI from the verifier redirect. | |
| 76 | |
| 77 | **Returns** |
| 78 | |
| 79 | `connected_account_complete_auth_response.ConnectedAccount...` — The completed `connected_account_id` and its `toolkit_slug`. |
| 80 | |
| 81 | **Example** |
| 82 | |
| 83 | ```python |
| 84 | result = composio.connected_accounts.complete_auth( |
| 85 | user_id="user_123", |
| 86 | session_uri=session_uri, # from the verifier redirect |
| 87 | ) |
| 88 | print(result.connected_account_id) |
| 89 | ``` |
| 90 | |
| 91 | --- |
| 92 | |
| 93 | ### update() |
| 94 | |
| 95 | Update a connected account's alias and/or credentials. |
| 96 | |
| 97 | ```python |
| 98 | def update(nanoid: str, *, alias: str | None = ..., connection: connected_account_patch_params.Connection | None = ...) -> connected_account_patch_response.ConnectedAccountPatchRes... |
| 99 | ``` |
| 100 | |
| 101 | **Parameters** |
| 102 | |
| 103 | | Name | Type | Description | |
| 104 | |------|------|-------------| |
| 105 | | `nanoid` | `str` | The connected account ID (ca_xxx). | |
| 106 | | `alias?` | `str \| None` | Human-readable alias. Pass an empty string to clear. Must be unique per entity and toolkit within the project. | |
| 107 | | `connection?` | `connected_account_patch_params.Connection \| None` | Credential update with authScheme and val fields. | |
| 108 | |
| 109 | **Returns** |
| 110 | |
| 111 | `connected_account_patch_response.ConnectedAccountPatchRes...` — Response with `id`, `status`, and `success`. |
| 112 | |
| 113 | **Example** |
| 114 | |
| 115 | ```python |
| 116 | # Set an alias |
| 117 | composio.connected_accounts.update('ca_abc123', alias='work-gmail') |
| 118 | |
| 119 | # Clear an alias |
| 120 | composio.connected_accounts.update('ca_abc123', alias='') |
| 121 | ``` |
| 122 | |
| 123 | --- |
| 124 | |
| 125 | ### update_acl() |
| 126 | |
| 127 | Update the per-user ACL on a SHARED connected account. Experimental — shape may change in future releases. Only valid on SHARED connections; raises `ComposioAclOnlyForSharedError` on a PRIVATE connection. Omit a parameter to leave it unchanged; pass an empty list to clear an allow/deny list. At least one parameter must be provided. |
| 128 | |
| 129 | ```python |
| 130 | def update_acl(nanoid: str, *, allow_all_users: bool | None = ..., allowed_user_ids: List[str] | None = ..., not_allowed_user_ids: List[str] | None = ...) -> connected_account_patch_response.ConnectedAccountPatchRes... |
| 131 | ``` |
| 132 | |
| 133 | **Parameters** |
| 134 | |
| 135 | | Name | Type | Description | |
| 136 | |------|------|-------------| |
| 137 | | `nanoid` | `str` | The connected account ID (`ca_xxx`). | |
| 138 | | `allow_all_users?` | `bool \| None` | When True, any `user_id` may use this SHARED connection (subject to the deny list). | |
| 139 | | `allowed_user_ids?` | `List[str] \| None` | Explicit list of allowed `user_id` strings. Pass `[]` to clear. | |
| 140 | | `not_allowed_user_ids?` | `List[str] \| None` | Explicit deny list (wins over allow on conflict). Pass `[]` to clear — note that clearing the deny list silently re-grants access to previously-blocked users. | |
| 141 | |
| 142 | **Returns** |
| 143 | |
| 144 | `connected_account_patch_response.ConnectedAccountPatchRes...` — Response with `id`, `status`, and `success`. |
| 145 | |
| 146 | **Example** |
| 147 | |
| 148 | ```python |
| 149 | composio.connected_accounts.update_acl( |
| 150 | 'ca_abc', |
| 151 | allow_all_users=True, |
| 152 | not_allowed_user_ids=['user_bob'], |
| 153 | ) |
| 154 | ``` |
| 155 | |
| 156 | --- |
| 157 | |
| 158 | ### initiate() |
| 159 | |
| 160 | Compound function to create a new connected account. This function creates a new connected account and returns a connection request. Users can then wait for the connection to be established using the `wait_for_connection` method. |
| 161 | |
| 162 | ```python |
| 163 | def initiate(user_id: str, auth_config_id: str, *, callback_url: str | None = ..., allow_multiple: bool = ..., config: connected_account_create_params.ConnectionState | None = ..., alias: str | None = ...) -> ConnectionRequest |
| 164 | ``` |
| 165 | |
| 166 | **Parameters** |
| 167 | |
| 168 | | Name | Type | Description | |
| 169 | |------|------|-------------| |
| 170 | | `user_id` | `str` | The user ID to create the connected account for. | |
| 171 | | `auth_config_id` | `str` | The auth config ID to create the connected account for. | |
| 172 | | `callback_url?` | `str \| None` | Callback URL to use for OAuth apps. | |
| 173 | | `allow_multiple?` | `bool` | Whether to allow multiple connected accounts for the same user and auth config. | |
| 174 | | `config?` | `connected_account_create_params.ConnectionState \| None` | The configuration to create the connected account with. | |
| 175 | | `alias?` | `str \| None` | Optional human-readable alias for the account. Must be unique per userId and toolkit within the project. | |
| 176 | |
| 177 | **Returns** |
| 178 | |
| 179 | `ConnectionRequest` — The connection request. |
| 180 | |
| 181 | --- |
| 182 | |
| 183 | ### link() |
| 184 | |
| 185 | Create a Composio Connect Link for a user to connect their account to a given auth config. This method will return an external link which you can use for the user to connect their account. |
| 186 | |
| 187 | ```python |
| 188 | def link(user_id: str, auth_config_id: str, *, callback_url: str | None = ..., alias: str | None = ..., allow_multiple: bool = ..., experimental: link_create_params.Experimental | None = ...) -> ConnectionRequest |
| 189 | ``` |
| 190 | |
| 191 | **Parameters** |
| 192 | |
| 193 | | Name | Type | Description | |
| 194 | |------|------|-------------| |
| 195 | | `user_id` | `str` | The external user ID to create the connected account for. | |
| 196 | | `auth_config_id` | `str` | The auth config ID to create the connected account for. | |
| 197 | | `callback_url?` | `str \| None` | The URL to redirect the user to post connecting their account. | |
| 198 | | `alias?` | `str \| None` | Optional human-readable alias for the connection. Must be unique per userId and toolkit within the project. | |
| 199 | | `allow_multiple?` | `bool` | Whether to allow multiple connected accounts for the same user and auth config. When False (default), raises `ComposioMultipleConnectedAccountsError` if the user already has an `ACTIVE` connection on this auth config. Pair with `alias` and a session-level `multi_account` config to disambiguate at execution time. | |
| 200 | | `experimental?` | `link_create_params.Experimental \| None` | Experimental options for this connection. Pass an `Experimental` dict with `account_type` and/or `acl_config_for_shared` to create a SHARED connection with a per-user ACL. Experimental — shape may change in future releases. | |
| 201 | |
| 202 | **Returns** |
| 203 | |
| 204 | `ConnectionRequest` — Connection request object. |
| 205 | |
| 206 | **Example** |
| 207 | |
| 208 | ```python |
| 209 | # Create a connection request and redirect the user to the redirect url |
| 210 | connection_request = composio.connected_accounts.link('user_123', 'auth_config_123') |
| 211 | redirect_url = connection_request.redirect_url |
| 212 | print(f"Visit: {redirect_url} to authenticate your account") |
| 213 | |
| 214 | # Wait for the connection to be established |
| 215 | connected_account = connection_request.wait_for_connection() |
| 216 | |
| 217 | # Create a connection request with callback URL |
| 218 | connection_request = composio.connected_accounts.link( |
| 219 | 'user_123', |
| 220 | 'auth_config_123', |
| 221 | callback_url='https://your-app.com/callback' |
| 222 | ) |
| 223 | redirect_url = connection_request.redirect_url |
| 224 | print(f"Visit: {redirect_url} to authenticate your account") |
| 225 | |
| 226 | # Wait for the connection to be established |
| 227 | connected_account = composio.connected_accounts.wait_for_connection(connection_request.id) |
| 228 | |
| 229 | connection_request = composio.connected_accounts.link( |
| 230 | 'user_creator', |
| 231 | 'auth_config_123', |
| 232 | experimental={ |
| 233 | 'account_type': 'SHARED', |
| 234 | 'acl_config_for_shared': { |
| 235 | 'allow_all_users': True, |
| 236 | 'not_allowed_user_ids': ['user_bob'], |
| 237 | }, |
| 238 | }, |
| 239 | ) |
| 240 | ``` |
| 241 | |
| 242 | --- |
| 243 | |
| 244 | ### wait_for_connection() |
| 245 | |
| 246 | Wait for connected account with given ID to be active |
| 247 | |
| 248 | ```python |
| 249 | def wait_for_connection(id: str, timeout: float | None = ...) -> connected_account_retrieve_response.ConnectedAccountRetri... |
| 250 | ``` |
| 251 | |
| 252 | **Parameters** |
| 253 | |
| 254 | | Name | Type | |
| 255 | |------|------| |
| 256 | | `id` | `str` | |
| 257 | | `timeout?` | `float \| None` | |
| 258 | |
| 259 | **Returns** |
| 260 | |
| 261 | `connected_account_retrieve_response.ConnectedAccountRetri...` |
| 262 | |
| 263 | --- |
| 264 | |
| 265 | [View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/connected_accounts.py#L400) |