Create & Manage Connections for Users

Learn how to securely manage and authenticate multiple user connections

Entities

• Each user is represented by a unique entity ID.
• If you have two users, default and Melissa, they will each have unique entity IDs.
• You can use an entity object to manage connected accounts and perform actions on behalf of a user, learn more here. Here’s how to retrieve an entity object:

Python

from composio import ComposioToolSet

toolset = ComposioToolSet()
entity = toolset.get_entity(id='default')

If entity ID is not specified, default will be used as the entity ID.

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.

Integrations & Connections

Integration

• An integration is your app’s configuration for services like Gmail or GitHub
• Each integration contains authentication method, API scopes, client credentials and other app settings
• Developers can create multiple integrations with different configurations, learn more here

Connection

• A connection links a user to an integration
• Multiple connections can be created for the same integration
• Learn how to use connections here

Initiating a new connection for your user

OAuth-Based Apps

1. Install libraries

   Python

   pip install composio-core
   
2. Import Libraries & Initialize Toolset

   Python

   from composio import ComposioToolSet, App 
   toolset = ComposioToolSet()
   
3. Initiate a new connection

   Below are the accepted parameters for initiating a new connection:

   • integration_id: ID of the existing integration, use this to create a connection for an existing integration, If no integration exists for the given app, new one is automatically created
   • app: name of the app to create a connection for
   • labels: labels to be assigned to the connection, which can later be used to filter connections
   • entity_id: ID of the user for whom the connection is being created
   • redirect_url: URL to redirect the user to after the connection is created (for OAuth auth scheme). If not provided, the user will be redirected to Composio’s connection success/failer page
   • connected_account_params/data: If auth mode is non-OAuth, this is where parameters need to be passed for creating a connection (API key, shopify store name, etc)
   • auth_scheme: Type of authentication to be used for the connection (OAUTH2 or API_KEY, BASIC_WITH_JWT, etc), OAUTH2 will be defaulted if not provided
   • auth_config: If auth mode is OAuth, this is where the configuration needs to be provided for creating a connection (client_id, client_secret, etc)

   Let’s create a connection for the user default for the Gmail app.

   Python

   # Store connection parameters
   redirect_url = "https://yourwebsite.com/connection/success"
   entity_id = "default" 
   
   connection_request = toolset.initiate_connection(redirect_url=redirect_url, entity_id=entity_id, app=App.GMAIL)
   

   Connection request output:

   Python

   connectionStatus='INITIATED'
   connectedAccountId='<connected_account_id>'
   redirectUrl='https://accounts.google.com...'
   

   • connectionStatus: status of the connection, initially it will be INITIATED and will change to ACTIVE or FAILED after user completes the auth flow
   • connectedAccountId: ID of the newly created account, you can use this ID to retrieve the connection object
   • redirectUrl: URL to redirect to perform authentication, post the authentication flow user will be redirect to the page specified in the redirectUrl parameter
4. Checking the status of the connection

   Use the connectedAccountId to get the detailed information about the connection, learn more here.

   Python

   connection = toolset.get_connected_account(id="83f5e791-e6c4-4cd6-8e3a-dada66b0a8f1")
   print(connection.status)
   

   Status of the connection can be one of the following:

   • INITIATED: Connection is initiated but not yet completed
   • ACTIVE: Connection is active and ready to use
   • FAILED: Connection failed to be created

Each App integration has a unique integration ID. You can use this ID instead of the app name when creating connections.

Non OAuth-Based Apps

1. Install libraries

   Python

   pip install composio-core
   
2. Import Libraries & Initialize Toolset

   Python

   from composio import ComposioToolSet, App 
   toolset = ComposioToolSet()
   
3. Collect parameters required to create a connection

   Get the expected parameters required to create a connection & pass them while initiating a new connection (API Key, Subdomain URL, Username etc.).

   Python

   # You can use integration_id instead of app
   response = toolset.get_expected_params_for_user(app=App.FIRECRAWL) 
   print(response["expected_params"])
   

   Response:

   [
     ExpectedFieldInput(
     name='api_key',
     type='string',
     description='Your FireCrawl API key for authentication. Obtain it from your FireCrawl settings.',
     displayName='API Key',
     is_secret=False,
     required=True,
     expected_from_customer=True,
     default=None,
     get_current_user_endpoint=None)
   ]
   

   To create a new connection for FireCrawl app, we need the FireCrawl API key

4. Initiate a new connection

   Below are the accepted parameters for initiating a new connection:

   • integration_id: ID of the existing integration, use this to create a connection for an existing integration, If no integration exists for the given app, new one is automatically created
   • app: name of the app to create a connection for
   • labels: labels to be assigned to the connection, which can later be used to filter connections
   • entity_id: ID of the user for whom the connection is being created
   • redirect_url: URL to redirect the user to after the connection is created (for OAuth auth scheme). If not provided, the user will be redirected to Composio’s connection success/failer page
   • connected_account_params/data: If auth mode is non-OAuth, this is where parameters need to be passed for creating a connection (API key, shopify store name, etc)
   • auth_scheme: Type of authentication to be used for the connection (OAUTH2 or API_KEY, etc), OAUTH2 will be defaulted if not provided
   • auth_config: If auth mode is OAuth, this is where the configuration needs to be provided for creating a connection (client_id, client_secret, etc)

   Let’s create a connection for the user default for the FireCrawl app.

   Python

   # Store connection parameters
   entity_id = "default"
   collected_params = {"api_key": "<firecrawl_api_key>"}
   auth_scheme = "API_KEY"
   
   # Initiate new connection (You can use integration_id instead of app)
   connection_request = toolset.initiate_connection(
       connected_account_params=collected_params,
       entity_id=entity_id,
       app=App.FIRECRAWL,
       auth_scheme=auth_scheme,
   )
   

   Connection request output:

   Python

   connectionStatus='ACTIVE' 
   connectedAccountId='<connected_account_id>' 
   redirectUrl=None
   

   • connectionStatus: status of the connection
   • connectedAccountId: ID of the newly created account, you can use this ID to retrieve the connection object
   • redirectUrl: URL to redirect to perform authentication, since its not an OAuth type auth scheme, redirectUrl will be None
5. Checking the status of the connection

   Use the connectedAccountId to get the detailed information about the connection, learn more here.

   Python

   connection = toolset.get_connected_account(id="<connected_account_id>")
   print(connection.status)
   

   Status of the connection can be one of the following:

   • INITIATED: Connection is initiated but not yet completed
   • ACTIVE: Connection is active and ready to use
   • FAILED: Connection failed to be created

Each App integration has a unique integration ID. You can use this ID instead of the app name when creating connections.