@devries-cameron20 / composio Mirror · read-only
Fork 0

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

next
mdx 265 lines 9.79 KB
Raw
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)