​
Introduction to Connected Accounts

  • When a user connects their account, a connected_account object is created.
  • Connected Account securely stores authentication data such as api keys, access tokens and refresh tokens.

​
Introduction to Entities

  • Each unique user/tenant is represented by a unique entity id.
  • If you have two users, Jessica and Melissa, they will each have unique entity ids.

​
Connecting an Account for your User

Connecting a user account requires a few API calls to authenticate and authorize access. The process involves:

  1. Fetching Parameters to create a Connection - Get the authentication requirements for the chosen application (API Key, Subdomain URL, Username etc.)
  2. Collecting those parameters from the user - Gather the required parameters from your user interface
  3. Creating a Connection - Initialize a new connection with the collected parameters
  4. Handling OAuth Flow - For OAuth applications, redirect the user to complete authorization
  5. Verifying Connection Status - Check that the connection was successful

​
Code Snippets for Connecting an Account

1

Collect Parameters Required to create a Connection

To create a connected account for your user:

  1. Fetch required auth parameters for the application
  2. Collect these parameters from the user
  3. Initiate a new connection request
Linear: Requires api_key, Shopify: Requires shop_name for OAuth flow

Collect the required parameters from your user through your preferred interface (UI, chat, or API).

All parameters should be provided as strings.

2

Try creating a connection with the parameters collected

In the code snippets below replace redirect_url

Some applications require user redirection to complete the authentication process. Gmail for example requires redirecting the user to Google’s login page.

3

How to get all Connected Accounts?

4

Fetch the Connection Params (Status, Access Token, Refresh Token...)

If you want to use connection params locally and build custom actions -

Connection status can be failed, initiated or active.

Example of how connection params would look like

You can fetch connection details after user is redirected back to your app. (If redirect was needed)

connection_status & connectedAccountId will be available in the query params.

​
Receiving Webhooks alerts on new Connections

Composio provides real-time webhook notifications for new connections. To utilize this feature:

  1. Set up webhook alerts in the Composio dashboard
  2. Configure your application to receive and parse the webhook payloads

This allows you to instantly track when users integrate new services with your application.

Was this page helpful?

Available Local ToolsEntities