​
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:
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

1

Install libraries

2

Import Libraries & Initialize Toolset

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.

Connection request output:

  • 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.

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.

Was this page helpful?

Suggest editsRaise issue
Serving Tools Over EndpointUsing Connections