Connected Accounts
A connected account is a single user's authorized connection to a toolkit. It stores their credentials (OAuth tokens or API keys) and links them to your user ID, so your tools can act on that user's behalf.
Composio creates a connected account when a user completes the flow defined by an auth config. From there you manage its full lifecycle:
- Create or link: start a new connection, or generate an auth link session for the user to authorize. See manually authenticating users.
- Refresh: renew authentication for an account whose tokens have expired.
- Enable, disable, or update: change an account's status or metadata without removing it.
- Revoke or delete: revoke the grant at the provider, or remove the account from Composio.
Each account is addressed by its nanoid. List endpoints accept filters so you can find accounts by user, toolkit, or auth config.
Link auth (Composio Connect Links)
A Composio Connect Link is a hosted, secure sign-in page. You create one with the create auth link session endpoint, redirect the user to the returned URL, and Composio handles the rest: the user signs in, Composio creates the connected account, and Composio stores and refreshes its tokens. Credentials never pass through your app. This works for all Composio managed connections, with no OAuth credentials to set up.
By default a connected account is PRIVATE and usable only by its owning user. Mark one SHARED to let other users reach it through a per-connection access control list. See shared connections.
These endpoints use your project API key in the x-api-key header.
Shared-connection ACL fields are experimental and nested under an experimental block on the wire. Pin a specific SDK version if you depend on the current shape.
Callback identity verification
Anyone who opens a Connect Link and consents becomes the account attached to that flow. On its own that is exploitable: someone starts a connection under their own user, copies the authorization URL before consenting, and gets a different person to finish it, attaching that person's provider account under the attacker's identity. This is OAuth session fixation. Callback identity verification defends against it by confirming the returning user before a connection activates.
Set a verifier URL on a project, and Composio holds every OAuth connection there until your server confirms who came back. After the provider callback, Composio redirects the browser to the endpoint you host with one query parameter, session_uri, which carries no connection id, user id, or toolkit name. From your server, authenticating with your project API key, you post the session_uri and the signed-in user_id to the complete auth endpoint. On a match the connection activates and returns its connected_account_id and toolkit_slug; a 200 comes back only once it is ACTIVE. Only a user_id that doesn't match fails the connection: the request returns 400, and the connection moves to FAILED with its status_reason set to Callback identity verification failed. Any other error leaves the connection pending, so you can restart the flow. The session_uri is single-use and valid for ten minutes; redeeming it spends the session whatever the outcome, so a repeat call returns 404.
Your endpoint owns the redirect from here: once you redeem the session, send the user onward yourself. A callback_url set when you create the connection is not used.
Turn it on in the dashboard under Settings → General → Configuration. The URL must be public HTTPS, and Composio rejects private and reserved addresses on save, so local development needs a tunnel. Verification is opt-in per project, and once set it covers every OAuth connection in the project that goes through a provider redirect, whether you start it from the API or a Connect Link.
Connections you start from the dashboard can't complete while a verifier URL is set. A dashboard connection is owned by a Composio dashboard user, which isn't one of your app's users and isn't disclosed to your endpoint, so your app can't report a matching user_id. Test from your own app, or clear the verifier URL while you work in the dashboard.
Endpoints
| Endpoint | Quick Link |
|---|---|
POST /api/v3.1/connected_accounts/{nanoid}/revoke | Revoke a connected account at the provider |
POST /api/v3.1/connected_accounts/complete_auth | Complete a deferred OAuth connection after identity verification |
GET /api/v3.1/connected_accounts | List connected accounts with optional filters |
POST /api/v3.1/connected_accounts | Create a new connected account |
GET /api/v3.1/connected_accounts/{nanoid} | Get connected account details by ID |
DELETE /api/v3.1/connected_accounts/{nanoid} | Delete a connected account |
PATCH /api/v3.1/connected_accounts/{nanoid} | Update a connected account |
PATCH /api/v3.1/connected_accounts/{nanoId}/status | Enable or disable a connected account |
POST /api/v3.1/connected_accounts/{nanoid}/refresh | Re-initiate authentication for a connected accountLegacy |
POST /api/v3.1/connected_accounts/link | Create a new auth link session |