Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Remove core concepts page

haxziedce9036f3acc
diff --git a/fern/docs.yml b/fern/docs.yml
index 278848dd4..7dd7974f1 100644
--- a/fern/docs.yml
+++ b/fern/docs.yml
@@ -101,30 +101,12 @@ navigation:
- page: Quickstart
path: pages/dist/get-started/quickstart.mdx
slug: quickstart
- - section: Core Concepts
- skip-slug: true
- contents:
- - page: Overview
- path: pages/dist/core-concepts/overview.mdx
- slug: core-concepts
- - page: User IDs
- path: pages/dist/core-concepts/user-ids.mdx
- slug: user-ids
- - page: Tools and Toolkits
- path: pages/dist/core-concepts/tools-and-toolkits.mdx
- slug: tools-and-toolkits
- - page: Providers
- path: pages/dist/core-concepts/providers.mdx
- slug: providers
- - page: Connected Accounts
- path: pages/dist/core-concepts/connected-accounts.mdx
- slug: connected-accounts
- - page: Auth Configs
- path: pages/dist/core-concepts/auth-configs.mdx
- slug: auth-configs
- - page: Triggers
- path: pages/dist/core-concepts/triggers.mdx
- slug: triggers
+ - page: IDE and Agent Setup
+ path: pages/dist/get-started/dev-setup.mdx
+ slug: ide-and-agent-setup
+ - page: Providers
+ path: pages/dist/get-started/providers.mdx
+ slug: providers
- section: Tools
icon: tools
skip-slug: true
@@ -196,9 +178,6 @@ navigation:
- page: Migration Guide
path: pages/dist/migration-guide.mdx
slug: migration
- - page: IDE and Agent Setup
- path: pages/dist/get-started/dev-setup.mdx
- slug: ide-and-agent-setup
- tab: examples
layout:
- section: Getting Started
diff --git a/fern/pages/src/core-concepts/auth-configs.mdx b/fern/pages/src/core-concepts/auth-configs.mdx
deleted file mode 100644
index bcaf9f3e9..000000000
--- a/fern/pages/src/core-concepts/auth-configs.mdx
+++ /dev/null
@@ -1,694 +0,0 @@
----
-title: Auth Configs
-subtitle: Understanding the auth configs in Composio
-image: 'https://og.composio.dev/api/og?title=Auth%20Configs' # image for socials
-keywords: ''
-hide-nav-links: true
----
-Auth Configs define how authentication works for each toolkit. They specify the authentication method, required credentials, and configuration needed for users to connect their accounts.
-
-## What Are Auth Configs?
-
-An Auth Config is a template that defines:
-- **Authentication Method**: OAuth2, API Key, Basic Auth, etc.
-- **Required Fields**: What credentials users need to provide
-- **Service Configuration**: OAuth app settings, API endpoints, scopes
-
-<CodeGroup>
-
-```python
-# Create an auth config for GitHub
-auth_config = await composio.auth_configs.create('github', {
- 'type': 'use_composio_managed_auth',
- 'name': 'GitHub Integration'
-})
-```
-```typescript
-// Create an auth config for GitHub
-const authConfig = await composio.authConfigs.create('github', {
- type: 'use_composio_managed_auth',
- name: 'GitHub Integration'
-});
-```
-
-</CodeGroup>
-
-## Auth Config Types
-
-### Composio Managed Auth
-Composio handles OAuth applications and credentials for you:
-
-<CodeGroup>
-
-
-```python
-auth_config = await composio.auth_configs.create('github', {
- 'type': 'use_composio_managed_auth',
- 'name': 'GitHub - Composio Managed'
-})
-```
-```typescript
-const authConfig = await composio.authConfigs.create('github', {
- type: 'use_composio_managed_auth',
- name: 'GitHub - Composio Managed'
-});
-```
-</CodeGroup>
-
-**Benefits:**
-- No OAuth app setup required
-- Composio handles token management
-- Quick setup for development and testing
-- Built-in security best practices
-
-### User Credentials
-Users provide their own API keys or credentials:
-
-<CodeGroup>
-
-
-```python
-auth_config = await composio.auth_configs.create('openai', {
- 'type': 'user_credentials',
- 'name': 'OpenAI API Key',
- 'fields': {
- 'api_key': {
- 'type': 'string',
- 'description': 'Your OpenAI API key',
- 'required': True
- }
- }
-})
-```
-```typescript
-const authConfig = await composio.authConfigs.create('openai', {
- type: 'user_credentials',
- name: 'OpenAI API Key',
- fields: {
- api_key: {
- type: 'string',
- description: 'Your OpenAI API key',
- required: true
- }
- }
-});
-```
-</CodeGroup>
-
-### Custom Auth
-Define custom authentication flows:
-
-<CodeGroup>
-```python Python
-auth_config = await composio.auth_configs.create('custom_service', {
- 'type': 'custom_auth',
- 'name': 'Custom Service Auth',
- 'fields': {
- 'client_id': {
- 'type': 'string',
- 'description': 'Your OAuth client ID',
- 'required': True
- },
- 'client_secret': {
- 'type': 'string',
- 'description': 'Your OAuth client secret',
- 'required': True,
- 'sensitive': True
- },
- 'redirect_uri': {
- 'type': 'string',
- 'description': 'OAuth redirect URI',
- 'default': 'https://backend.composio.dev/api/v1/auth-apps/add'
- }
- }
-})
-```
-
-```typescript TypeScript
-const authConfig = await composio.authConfigs.create('custom_service', {
- type: 'custom_auth',
- name: 'Custom Service Auth',
- fields: {
- client_id: {
- type: 'string',
- description: 'Your OAuth client ID',
- required: true
- },
- client_secret: {
- type: 'string',
- description: 'Your OAuth client secret',
- required: true,
- sensitive: true
- },
- redirect_uri: {
- type: 'string',
- description: 'OAuth redirect URI',
- default: 'https://backend.composio.dev/api/v1/auth-apps/add'
- }
- }
-});
-```
-</CodeGroup>
-
-### No Auth
-For public APIs that don't require authentication:
-
-<CodeGroup>
-```python Python
-auth_config = await composio.auth_configs.create('hackernews', {
- 'type': 'no_auth',
- 'name': 'HackerNews Public API'
-})
-```
-
-```typescript TypeScript
-const authConfig = await composio.authConfigs.create('hackernews', {
- type: 'no_auth',
- name: 'HackerNews Public API'
-});
-```
-</CodeGroup>
-
-## Authentication Schemes
-
-Auth configs support different authentication schemes:
-
-### OAuth2
-Most modern services use OAuth2:
-
-<CodeGroup>
-
-```python
-# Get required fields for OAuth2 setup
-fields = await composio.toolkits.get_auth_config_creation_fields('github', 'OAUTH2')
-
-# Create OAuth2 auth config
-auth_config = await composio.auth_configs.create('github', {
- 'type': 'custom_auth',
- 'name': 'My GitHub App',
- 'fields': {
- 'client_id': 'your_github_client_id',
- 'client_secret': 'your_github_client_secret',
- 'scopes': 'repo,user:email'
- }
-})
-```
-```typescript
-// Get required fields for OAuth2 setup
-const fields = await composio.toolkits.getAuthConfigCreationFields('github', 'OAUTH2');
-
-// Create OAuth2 auth config
-const authConfig = await composio.authConfigs.create('github', {
- type: 'custom_auth',
- name: 'My GitHub App',
- fields: {
- client_id: 'your_github_client_id',
- client_secret: 'your_github_client_secret',
- scopes: 'repo,user:email'
- }
-});
-```
-
-</CodeGroup>
-
-### API Key
-Services that use API keys for authentication:
-
-<CodeGroup>
-
-```python
-auth_config = await composio.auth_configs.create('openai', {
- 'type': 'user_credentials',
- 'name': 'OpenAI API',
- 'fields': {
- 'api_key': 'user_will_provide_this'
- }
-})
-```
-```typescript
-const authConfig = await composio.authConfigs.create('openai', {
- type: 'user_credentials',
- name: 'OpenAI API',
- fields: {
- api_key: 'user_will_provide_this'
- }
-});
-```
-
-</CodeGroup>
-
-### Basic Auth
-Username and password authentication:
-
-<CodeGroup>
-
-```python
-auth_config = await composio.auth_configs.create('basic_service', {
- 'type': 'user_credentials',
- 'name': 'Basic Auth Service',
- 'fields': {
- 'username': 'user_username',
- 'password': 'user_password'
- }
-})
-```
-```typescript
-const authConfig = await composio.authConfigs.create('basic_service', {
- type: 'user_credentials',
- name: 'Basic Auth Service',
- fields: {
- username: 'user_username',
- password: 'user_password'
- }
-});
-```
-
-</CodeGroup>
-
-## Working with Auth Configs
-
-### List Auth Configs
-<CodeGroup>
-
-
-```python
-# Get all auth configs
-auth_configs = await composio.auth_configs.list()
-
-# Filter by toolkit
-github_configs = await composio.auth_configs.list(
- toolkit='github'
-)
-```
-```typescript
-// Get all auth configs
-const authConfigs = await composio.authConfigs.list();
-
-// Filter by toolkit
-const githubConfigs = await composio.authConfigs.list({
- toolkit: 'github'
-});
-```
-</CodeGroup>
-
-### Get Specific Auth Config
-<CodeGroup>
-
-```python
-auth_config = await composio.auth_configs.get('auth_config_123')
-
-print('Name:', auth_config.name)
-print('Type:', auth_config.type)
-print('Toolkit:', auth_config.toolkit.slug)
-print('Auth Scheme:', auth_config.auth_scheme)
-```
-```typescript
-const authConfig = await composio.authConfigs.get('auth_config_123');
-
-console.log('Name:', authConfig.name);
-console.log('Type:', authConfig.type);
-console.log('Toolkit:', authConfig.toolkit.slug);
-console.log('Auth Scheme:', authConfig.authScheme);
-```
-
-</CodeGroup>
-
-### Update Auth Config
-<CodeGroup>
-
-```python
-updated_config = await composio.auth_configs.update('auth_config_123', {
- 'name': 'Updated GitHub Integration',
- 'fields': {
- 'client_id': 'new_client_id',
- 'client_secret': 'new_client_secret'
- }
-})
-```
-```typescript
-const updatedConfig = await composio.authConfigs.update('auth_config_123', {
- name: 'Updated GitHub Integration',
- fields: {
- client_id: 'new_client_id',
- client_secret: 'new_client_secret'
- }
-});
-```
-
-</CodeGroup>
-
-### Delete Auth Config
-<CodeGroup>
-
-```python
-await composio.auth_configs.delete('auth_config_123')
-```
-```typescript
-await composio.authConfigs.delete('auth_config_123');
-```
-
-</CodeGroup>
-
-## Configuration Requirements
-
-### Get Required Fields
-Before creating auth configs, check what fields are required:
-
-<CodeGroup>
-
-```python
-# Get fields needed for creating an auth config
-creation_fields = await composio.toolkits.get_auth_config_creation_fields(
- 'github',
- 'OAUTH2'
-)
-
-print('Required fields:', creation_fields)
-# Output:
-# [
-# {
-# 'name': 'client_id',
-# 'display_name': 'Client ID',
-# 'type': 'string',
-# 'required': True
-# },
-# {
-# 'name': 'client_secret',
-# 'display_name': 'Client Secret',
-# 'type': 'string',
-# 'required': True
-# }
-# ]
-```
-```typescript
-// Get fields needed for creating an auth config
-const creationFields = await composio.toolkits.getAuthConfigCreationFields(
- 'github',
- 'OAUTH2'
-);
-
-console.log('Required fields:', creationFields);
-// Output:
-// [
-// {
-// name: 'client_id',
-// displayName: 'Client ID',
-// type: 'string',
-// required: true
-// },
-// {
-// name: 'client_secret',
-// displayName: 'Client Secret',
-// type: 'string',
-// required: true
-// }
-// ]
-```
-
-</CodeGroup>
-
-### Get Connection Fields
-Check what users need to provide when connecting:
-
-<CodeGroup>
-
-```python
-# Get fields needed for user connection
-connection_fields = await composio.toolkits.get_connected_account_initiation_fields(
- 'shopify',
- 'OAUTH2'
-)
-
-print('User must provide:', connection_fields)
-# Output:
-# [
-# {
-# 'name': 'shop',
-# 'display_name': 'Store Subdomain',
-# 'type': 'string',
-# 'required': True
-# }
-# ]
-```
-```typescript
-// Get fields needed for user connection
-const connectionFields = await composio.toolkits.getConnectedAccountInitiationFields(
- 'shopify',
- 'OAUTH2'
-);
-
-console.log('User must provide:', connectionFields);
-// Output:
-// [
-// {
-// name: 'shop',
-// displayName: 'Store Subdomain',
-// type: 'string',
-// required: true
-// }
-// ]
-```
-
-</CodeGroup>
-
-### Missing Fields
-<CodeGroup>
-
-```python
-# Check what fields are required
-fields = await composio.toolkits.get_auth_config_creation_fields('toolkit', 'OAUTH2')
-print('Required fields:', [f for f in fields if f.required])
-```
-```typescript
-// Check what fields are required
-const fields = await composio.toolkits.getAuthConfigCreationFields('toolkit', 'OAUTH2');
-console.log('Required fields:', fields.filter(f => f.required));
-```
-
-</CodeGroup>
-
-## OAuth App Setup
-
-### GitHub Example
-<CodeGroup>
-
-```python
-# 1. Create OAuth app in GitHub
-# 2. Get client ID and secret
-# 3. Create auth config in Composio
-
-github_auth = await composio.auth_configs.create('github', {
- 'type': 'custom_auth',
- 'name': 'My GitHub App',
- 'fields': {
- 'client_id': 'your_github_client_id',
- 'client_secret': 'your_github_client_secret',
- 'scopes': 'repo,user:email'
- }
-})
-```
-```typescript
-// 1. Create OAuth app in GitHub
-// 2. Get client ID and secret
-// 3. Create auth config in Composio
-
-const githubAuth = await composio.authConfigs.create('github', {
- type: 'custom_auth',
- name: 'My GitHub App',
- fields: {
- client_id: 'your_github_client_id',
- client_secret: 'your_github_client_secret',
- scopes: 'repo,user:email'
- }
-});
-```
-
-</CodeGroup>
-
-### Google Example
-
-
-<CodeGroup>
-
-```python
-google_auth = await composio.auth_configs.create('gmail', {
- 'type': 'custom_auth',
- 'name': 'My Google App',
- 'fields': {
- 'client_id': os.environ.get('GOOGLE_CLIENT_ID'),
- 'client_secret': os.environ.get('GOOGLE_CLIENT_SECRET'),
- 'oauth_redirect_uri': 'https://backend.composio.dev/api/v1/auth-apps/add',
- 'scopes': 'https://www.googleapis.com/auth/gmail.modify'
- }
-})
-```
-```typescript
-const googleAuth = await composio.authConfigs.create('gmail', {
- type: 'custom_auth',
- name: 'My Google App',
- fields: {
- client_id: process.env.GOOGLE_CLIENT_ID,
- client_secret: process.env.GOOGLE_CLIENT_SECRET,
- oauth_redirect_uri: 'https://backend.composio.dev/api/v1/auth-apps/add',
- scopes: 'https://www.googleapis.com/auth/gmail.modify'
- }
-});
-```
-
-</CodeGroup>
-
-## Using Auth Configs
-
-### With Connected Accounts
-
-<CodeGroup>
-
-
-```python
-# Create connected account using specific auth config
-connection = await composio.connected_accounts.initiate(
- 'user_123',
- 'auth_config_456', # Specific auth config ID
- config=AuthScheme.api_key(
- api_key='user_provided_key'
- )
-)
-```
-```typescript
-// Create connected account using specific auth config
-const connection = await composio.connectedAccounts.initiate(
- 'user_123',
- 'auth_config_456', // Specific auth config ID
- {
- config: AuthScheme.ApiKey({
- api_key: 'user_provided_key'
- })
- }
-);
-```
-</CodeGroup>
-
-### Automatic Selection
-
-<CodeGroup>
-
-```python
-# Composio automatically selects appropriate auth config
-connection = await composio.toolkits.authorize('user_123', 'github')
-```
-```typescript
-// Composio automatically selects appropriate auth config
-const connection = await composio.toolkits.authorize('user_123', 'github');
-```
-</CodeGroup>
-
-## Best Practices
-
-### Development vs Production
-<CodeGroup>
-
-```python
-# Development - use Composio managed auth
-dev_config = await composio.auth_configs.create('github', {
- 'type': 'use_composio_managed_auth',
- 'name': 'GitHub Dev'
-})
-
-# Production - use your own OAuth app
-prod_config = await composio.auth_configs.create('github', {
- 'type': 'custom_auth',
- 'name': 'GitHub Production',
- 'fields': {
- 'client_id': os.environ.get('GITHUB_CLIENT_ID'),
- 'client_secret': os.environ.get('GITHUB_CLIENT_SECRET')
- }
-})
-```
-```typescript
-// Development - use Composio managed auth
-const devConfig = await composio.authConfigs.create('github', {
- type: 'use_composio_managed_auth',
- name: 'GitHub Dev'
-});
-
-// Production - use your own OAuth app
-const prodConfig = await composio.authConfigs.create('github', {
- type: 'custom_auth',
- name: 'GitHub Production',
- fields: {
- client_id: process.env.GITHUB_CLIENT_ID,
- client_secret: process.env.GITHUB_CLIENT_SECRET
- }
-});
-```
-
-</CodeGroup>
-
-### Secure Credential Management
-<CodeGroup>
-
-
-```python
-# Use environment variables for sensitive data
-auth_config = await composio.auth_configs.create('service', {
- 'type': 'custom_auth',
- 'name': 'Service Auth',
- 'fields': {
- 'client_id': os.environ.get('SERVICE_CLIENT_ID'),
- 'client_secret': os.environ.get('SERVICE_CLIENT_SECRET'),
- # Never hardcode secrets in your code
- }
-})
-```
-```typescript
-// Use environment variables for sensitive data
-const authConfig = await composio.authConfigs.create('service', {
- type: 'custom_auth',
- name: 'Service Auth',
- fields: {
- client_id: process.env.SERVICE_CLIENT_ID,
- client_secret: process.env.SERVICE_CLIENT_SECRET,
- // Never hardcode secrets in your code
- }
-});
-```
-</CodeGroup>
-
-## Troubleshooting
-
-### OAuth Redirect Issues
-- Ensure redirect URI matches exactly
-- Check if the OAuth app is configured correctly
-- Verify the redirect URI is accessible
-
-### Missing Fields
-```javascript
-// Check what fields are required
-const fields = await composio.toolkits.getAuthConfigCreationFields('toolkit', 'OAUTH2');
-console.log('Required fields:', fields.filter(f => f.required));
-```
-
-### Connection Failures
-- Verify client ID and secret are correct
-- Check OAuth app permissions and scopes
-- Ensure the auth config is not disabled
-
-## Security Considerations
-
-### Credential Protection
-- Never commit secrets to version control
-- Use environment variables or secure secret management
-- Rotate credentials regularly
-
-### Scope Management
-- Request only necessary permissions
-- Use least privilege principle
-- Document required scopes clearly
-
-### Access Control
-- Limit who can create/modify auth configs
-- Use different configs for different environments
-- Monitor auth config usage
-
-
-Auth configs are the foundation of secure authentication in Composio. Understanding how to create and manage them effectively ensures your users can safely connect their accounts to your application.
\ No newline at end of file
diff --git a/fern/pages/src/core-concepts/connected-accounts.mdx b/fern/pages/src/core-concepts/connected-accounts.mdx
deleted file mode 100644
index 65175420d..000000000
--- a/fern/pages/src/core-concepts/connected-accounts.mdx
+++ /dev/null
@@ -1,593 +0,0 @@
----
-title: Connected Accounts
-subtitle: Understanding the connected accounts in Composio
-image: 'https://og.composio.dev/api/og?title=Connected%20Accounts' # image for socials
-keywords: ''
-hide-nav-links: true
----
-Connected Accounts represent a user's authorized connection to an external service. They store authentication tokens and credentials needed to execute tools on behalf of the user.
-
-## What Are Connected Accounts?
-
-A Connected Account is created when a user authorizes your application to access their external service account (like GitHub, Gmail, or Slack). It acts as a secure bridge between your application and the external service.
-
-<CodeGroup>
-```python
-# A connected account enables tool execution
-result = await composio.tools.execute('GITHUB_GET_REPO',
- user_id='user_123',
- connected_account_id='ca_abc123', # References the connected account
- arguments={'owner': 'composio', 'repo': 'sdk'}
-)
-```
-```typescript
-// A connected account enables tool execution
-const result = await composio.tools.execute('GITHUB_GET_REPO', {
- userId: 'user_123',
- connectedAccountId: 'ca_abc123', // References the connected account
- arguments: { owner: 'composio', repo: 'sdk' }
-});
-```
-
-</CodeGroup>
-
-## The Connection Flow
-
-### 1. Initiate Connection
-Start the authorization process for a user and toolkit:
-
-<CodeGroup>
-```python
-connection_request = await composio.toolkits.authorize(
- 'user_123', # Your user's ID
- 'github' # Toolkit to connect
-)
-
-print('Redirect user to:', connection_request.redirect_url)
-```
-```typescript
-const connectionRequest = await composio.toolkits.authorize(
- 'user_123', // Your user's ID
- 'github' // Toolkit to connect
-);
-
-console.log('Redirect user to:', connectionRequest.redirectUrl);
-```
-
-</CodeGroup>
-
-If your want to use a specific auth config, you can do so by passing the auth config ID to the `initiate` method:
-
-<CodeGroup>
-```python Python
-connection_request = await composio.connected_accounts.initiate(
- 'user_123',
- 'ac_123322' # Auth config ID to connect
-)
-```
-
-```typescript TypeScript
-const connectionRequest = await composio.connectedAccounts.initiate(
- 'user_123',
- 'ac_123322' // Auth config ID to connect
-);
-```
-</CodeGroup>
-
-### 2. User Authorization
-The user visits the redirect URL and authorizes access through the external service (OAuth flow).
-
-### 3. Connection Completion
-Wait for the user to complete authorization:
-
-<CodeGroup>
-```python Python
-connected_account = await connection_request.wait_for_connection(
- 120000 # 2 minutes timeout
-)
-
-print('Connected account ID:', connected_account.id)
-```
-
-```typescript TypeScript
-const connectedAccount = await connectionRequest.waitForConnection(
- 120000 // 2 minutes timeout
-);
-
-console.log('Connected account ID:', connectedAccount.id);
-```
-</CodeGroup>
-
-### 4. Use Connected Account
-Execute tools using the connected account:
-
-<CodeGroup>
-```python Python
-repos = await composio.tools.execute('GITHUB_LIST_REPOS',
- user_id='user_123',
- connected_account_id=connected_account.id,
- arguments={'per_page': 10}
-)
-```
-
-```typescript TypeScript
-const repos = await composio.tools.execute('GITHUB_LIST_REPOS', {
- userId: 'user_123',
- connectedAccountId: connectedAccount.id,
- arguments: { per_page: 10 }
-});
-```
-</CodeGroup>
-
-## Authentication Schemes
-
-Connected accounts support different authentication methods:
-
-### OAuth2 (Most Common)
-<CodeGroup>
-```python
-# OAuth2 flow - user authorizes in browser
-connection_request = await composio.toolkits.authorize('user_123', 'github')
-#-- or use connected_accounts.initiate for specific auth config
-connection_request = await composio.connected_accounts.initiate('user_123', 'ac_123322')
-
-# use the redirect_url to redirect the user to the auth flow
-print(connection_request.redirect_url)
-
-# User completes OAuth flow at connection.redirect_url
-connected_account = await connection_request.wait_for_connection()
-```
-```typescript
-// OAuth2 flow - user authorizes in browser
-const connectionRequest = await composio.toolkits.authorize('user_123', 'github');
-//-- or use connectedAccounts.initiate for specific auth config
-const connectionRequest = await composio.connectedAccounts.initiate('user_123', 'ac_123322');
-
-// use the redirectUrl to redirect the user to the auth flow
-console.log(connectionRequest.redirectUrl);
-
-// User completes OAuth flow at connection.redirectUrl
-const connectedAccount = await connectionRequest.waitForConnection();
-```
-
-</CodeGroup>
-
-### API Keys
-<CodeGroup>
-
-```python
-# User provides their API key
-connection = await composio.connected_accounts.initiate(
- 'user_123',
- 'auth_config_id',
- config=AuthScheme.api_key(
- api_key='user_provided_key'
- )
-)
-```
-
-```typescript
-// User provides their API key
-const connection = await composio.connectedAccounts.initiate(
- 'user_123',
- 'auth_config_id',
- {
- config: AuthScheme.ApiKey({
- api_key: 'user_provided_key'
- })
- }
-);
-```
-
-
-</CodeGroup>
-
-### Basic Authentication
-<CodeGroup>
-
-
-```python
-# Username and password
-connection = await composio.connected_accounts.initiate(
- 'user_123',
- 'auth_config_id',
- config=AuthScheme.basic(
- username='user_name',
- password='user_password'
- )
-)
-```
-```typescript
-// Username and password
-const connection = await composio.connectedAccounts.initiate(
- 'user_123',
- 'auth_config_id',
- {
- config: AuthScheme.Basic({
- username: 'user_name',
- password: 'user_password'
- })
- }
-);
-```
-</CodeGroup>
-
-### Bearer Tokens
-<CodeGroup>
-
-```python
-# Bearer token authentication
-connection = await composio.connected_accounts.initiate(
- 'user_123',
- 'auth_config_id',
- config=AuthScheme.bearer_token(
- token='bearer_token_value'
- )
-)
-```
-```typescript
-// Bearer token authentication
-const connection = await composio.connectedAccounts.initiate(
- 'user_123',
- 'auth_config_id',
- {
- config: AuthScheme.BearerToken({
- token: 'bearer_token_value'
- })
- }
-);
-```
-
-</CodeGroup>
-
-## Managing Connected Accounts
-
-### List User's Connections
-<CodeGroup>
-
-
-```python
-# Get all connected accounts for a user
-accounts = await composio.connected_accounts.list(
- user_ids=['user_123']
-)
-
-# Filter by specific toolkit
-github_accounts = await composio.connected_accounts.list(
- user_ids=['user_123'],
- toolkit_slugs=['github']
-)
-```
-```typescript
-// Get all connected accounts for a user
-const accounts = await composio.connectedAccounts.list({
- userIds: ['user_123']
-});
-
-// Filter by specific toolkit
-const githubAccounts = await composio.connectedAccounts.list({
- userIds: ['user_123'],
- toolkitSlugs: ['github']
-});
-```
-</CodeGroup>
-
-### Check Connection Status
-<CodeGroup>
-
-```python
-account = await composio.connected_accounts.get('ca_abc123')
-
-print('Status:', account.status) # 'ACTIVE', 'PENDING', 'EXPIRED'
-print('Toolkit:', account.toolkit.slug)
-print('User:', account.user_id)
-```
-```typescript
-const account = await composio.connectedAccounts.get('ca_abc123');
-
-console.log('Status:', account.status); // 'ACTIVE', 'PENDING', 'EXPIRED'
-console.log('Toolkit:', account.toolkit.slug);
-console.log('User:', account.userId);
-```
-
-</CodeGroup>
-
-### Disable/Enable Connections
-<CodeGroup>
-
-```python
-# Temporarily disable a connection
-await composio.connected_accounts.disable('ca_abc123')
-
-# Re-enable when needed
-await composio.connected_accounts.enable('ca_abc123')
-```
-```typescript
-// Temporarily disable a connection
-await composio.connectedAccounts.disable('ca_abc123');
-
-// Re-enable when needed
-await composio.connectedAccounts.enable('ca_abc123');
-```
-
-</CodeGroup>
-
-### Delete Connections
-<CodeGroup>
-
-```python
-# Permanently remove a connection
-await composio.connected_accounts.delete('ca_abc123')
-```
-```typescript
-// Permanently remove a connection
-await composio.connectedAccounts.delete('ca_abc123');
-```
-
-</CodeGroup>
-
-
-## Multiple Accounts
-
-By default, Composio prevents multiple connected accounts for the same toolkit to avoid conflicts. You can override this behavior:
-
-<CodeGroup>
-
-```python
-# Allow multiple connections for the same toolkit
-connection = await composio.connected_accounts.initiate(
- 'user_123',
- 'auth_config_id',
- allow_multiple=True
-)
-```
-```typescript
-// Allow multiple connections for the same toolkit
-const connection = await composio.connectedAccounts.initiate(
- 'user_123',
- 'auth_config_id',
- {
- allowMultiple: true
- }
-);
-```
-</CodeGroup>
-
-**Use cases for multiple accounts:**
-- User has multiple GitHub accounts (personal + work)
-- Different email accounts for different purposes
-- Separate accounts for different environments
-
-## Error Handling
-
-### Connection Timeout
-<CodeGroup>
-
-```python
-try:
- account = await composio.connected_accounts.wait_for_connection(
- connection_id,
- 300000 # 5 minutes
- )
-except ConnectionRequestTimeoutError:
- print('User did not complete authorization in time')
-```
-```typescript
-try {
- const account = await composio.connectedAccounts.waitForConnection(
- connectionId,
- 300000 // 5 minutes
- );
-} catch (error) {
- if (error instanceof ConnectionRequestTimeoutError) {
- console.log('User did not complete authorization in time');
- }
-}
-```
-
-</CodeGroup>
-
-### Connection Failed
-<CodeGroup>
-
-
-```python
-try:
- account = await composio.connected_accounts.wait_for_connection(connection_id)
-except ConnectionRequestFailedError:
- print('Authorization was denied or failed')
-```
-```typescript
-try {
- const account = await composio.connectedAccounts.waitForConnection(connectionId);
-} catch (error) {
- if (error instanceof ConnectionRequestFailedError) {
- console.log('Authorization was denied or failed');
- }
-}
-```
-</CodeGroup>
-
-### Missing Connected Account
-<CodeGroup>
-
-```python
-try:
- result = await composio.tools.execute('GITHUB_GET_REPO',
- user_id='user_123',
- arguments={'owner': 'composio', 'repo': 'sdk'}
- )
-except MissingConnectedAccountError:
- print('User needs to connect their GitHub account first')
-```
-```typescript
-try {
- const result = await composio.tools.execute('GITHUB_GET_REPO', {
- userId: 'user_123',
- arguments: { owner: 'composio', repo: 'sdk' }
- });
-} catch (error) {
- if (error instanceof MissingConnectedAccountError) {
- console.log('User needs to connect their GitHub account first');
- }
-}
-```
-
-</CodeGroup>
-
-## Best Practices
-
-### Connection Management
-<CodeGroup>
-
-
-```python
-# Check for existing connections before creating new ones
-async def ensure_connection(user_id: str, toolkit: str):
- existing = await composio.connected_accounts.list(
- user_ids=[user_id],
- toolkit_slugs=[toolkit]
- )
-
- if len(existing.items) > 0 and existing.items[0].status == 'ACTIVE':
- return existing.items[0]
-
- # Create new connection
- connection = await composio.toolkits.authorize(user_id, toolkit)
- return await composio.connected_accounts.wait_for_connection(connection.id)
-```
-```typescript
-// Check for existing connections before creating new ones
-async function ensureConnection(userId: string, toolkit: string) {
- const existing = await composio.connectedAccounts.list({
- userIds: [userId],
- toolkitSlugs: [toolkit]
- });
-
- if (existing.items.length > 0 && existing.items[0].status === 'ACTIVE') {
- return existing.items[0];
- }
-
- // Create new connection
- const connection = await composio.toolkits.authorize(userId, toolkit);
- return await composio.connectedAccounts.waitForConnection(connection.id);
-}
-```
-</CodeGroup>
-
-### Graceful Degradation
-
-<CodeGroup>
-
-
-```python
-# Handle missing connections gracefully
-async def execute_with_fallback(user_id: str, tool_slug: str, args: dict):
- try:
- return await composio.tools.execute(tool_slug,
- user_id=user_id,
- arguments=args
- )
- except ComposioConnectedAccountNotFoundError:
- # Return connection URL instead of failing
- connection = await composio.toolkits.authorize(user_id, 'github')
- return {
- 'requires_connection': True,
- 'redirect_url': connection.redirect_url
- }
-```
-```typescript
-// Handle missing connections gracefully
-async function executeWithFallback(userId: string, toolSlug: string, args: Record<string, any>) {
- try {
- return await composio.tools.execute(toolSlug, {
- userId,
- arguments: args
- });
- } catch (error) {
- if (error instanceof ComposioConnectedAccountNotFoundError) {
- // Return connection URL instead of failing
- const connection = await composio.toolkits.authorize(userId, 'github');
- return {
- requiresConnection: true,
- redirectUrl: connection.redirectUrl
- };
- }
- throw error;
- }
-}
-```
-</CodeGroup>
-
-### Connection Health Monitoring
-
-<CodeGroup>
-
-
-```python
-# Periodically check connection health
-async def check_connection_health(user_id: str):
- accounts = await composio.connected_accounts.list(
- user_ids=[user_id]
- )
-
- unhealthy = [
- account for account in accounts.items
- if account.status != 'ACTIVE'
- ]
-
- if len(unhealthy) > 0:
- print(f"User {user_id} has {len(unhealthy)} unhealthy connections")
- # Notify user or attempt refresh
-```
-```typescript
-// Periodically check connection health
-async function checkConnectionHealth(userId: string) {
- const accounts = await composio.connectedAccounts.list({
- userIds: [userId]
- });
-
- const unhealthy = accounts.items.filter(
- account => account.status !== 'ACTIVE'
- );
-
- if (unhealthy.length > 0) {
- console.log(`User ${userId} has ${unhealthy.length} unhealthy connections`);
- // Notify user or attempt refresh
- }
-}
-```
-</CodeGroup>
-
-## Security Considerations
-
-### Token Storage
-Composio securely stores all authentication tokens. You never need to handle sensitive credentials directly.
-
-### Access Control
-Connected accounts are scoped to specific users. One user cannot access another user's connected accounts.
-
-### Token Refresh
-Composio automatically handles token refresh for OAuth2 connections when possible.
-
-### Secure Deletion
-When a connected account is deleted, all associated tokens are securely removed.
-
-## Troubleshooting
-
-### Connection Stuck in PENDING
-- Check if user completed the OAuth flow
-- Verify the redirect URL is accessible
-- Increase the timeout duration
-
-### EXPIRED Connections
-- Try refreshing the connection
-- If refresh fails, user needs to reconnect
-
-### Multiple Connections Not Working
-- Ensure `allowMultiple: true` is set
-- Check if the auth config supports multiple connections
-
----
-
-Connected accounts are the bridge between your users and external services. Understanding how to create, manage, and use them effectively is crucial for building reliable integrations.
\ No newline at end of file
diff --git a/fern/pages/src/core-concepts/overview.mdx b/fern/pages/src/core-concepts/overview.mdx
deleted file mode 100644
index 971c6925b..000000000
--- a/fern/pages/src/core-concepts/overview.mdx
+++ /dev/null
@@ -1,560 +0,0 @@
----
-title: Core Concepts
-subtitle: Overview of the core concepts of Composio
-image: 'https://og.composio.dev/api/og?title=Core%20Concepts' # image for socials
-keywords: ''
-hide-nav-links: true
----
-
-Understanding Composio's core concepts is essential for building robust applications. This guide explains the fundamental building blocks and how they work together to provide seamless integration with external services.
-
-## Essential Concepts
-
-### 1. **User IDs** - The Foundation
-
-User IDs are the cornerstone of Composio's security model. Every operation requires a User ID to ensure proper data isolation. You can use the default user ID `default` for public APIs, or create a user ID for each user in your application.
-
-<CodeGroup>
-```python Python
-# ✅ Each user has their own isolated context
-user_a_tools = await composio.tools.get('user_a', toolkits=['github'])
-user_b_tools = await composio.tools.get('user_b', toolkits=['github'])
-```
-
-```typescript TypeScript
-// ✅ Each user has their own isolated context
-const userATools = await composio.tools.get('user_a', { toolkits: ['github'] });
-const userBTools = await composio.tools.get('user_b', { toolkits: ['github'] });
-```
-</CodeGroup>
-
-**Why User IDs Matter:**
-
-- **Security**: Prevents users from accessing each other's data
-- **Isolation**: Each user's connected accounts are separate
-- **Scaling**: Supports multi-tenant applications
-- **Compliance**: Meets data privacy requirements
-
-[**→ Learn more about User IDs**](./user-ids)
-
-
-### 2. **Tools** - Individual Actions
-
-Tools are specific actions you can perform, like "Get GitHub Repository" or "Send Email". Each tool has defined inputs and outputs.
-
-<CodeGroup>
-```python Python
-# A tool execution
-result = await composio.tools.execute('GITHUB_GET_REPO',
- user_id='user_123',
- arguments={
- 'owner': 'composio',
- 'repo': 'sdk'
- }
-)
-```
-
-```typescript TypeScript
-// A tool execution
-const result = await composio.tools.execute('GITHUB_GET_REPO', {
- userId: 'user_123',
- arguments: {
- owner: 'composio',
- repo: 'sdk',
- },
-});
-```
-</CodeGroup>
-
-**Tool Properties:**
-
-- **Slug**: Unique identifier (e.g., `GITHUB_GET_REPO`)
-- **Input Parameters**: What data the tool needs
-- **Output**: What data the tool returns
-- **Authentication**: Whether the tool requires user authorization
-
-
-### 3. **Toolkits** - Collections of Tools
-
-Toolkits group related tools from the same service. For example, the GitHub toolkit contains tools for repositories, issues, pull requests, and more.
-
-<CodeGroup>
-```python Python
-# Get all tools from the GitHub toolkit
-github_tools = await composio.tools.get('user_123',
- toolkits=['github']
-)
-
-# Available toolkits include: gmail, slack, notion, hubspot, salesforce, etc.
-```
-
-```typescript TypeScript
-// Get all tools from GitHub toolkit
-const githubTools = await composio.tools.get('user_123', {
- toolkits: ['github'],
-});
-
-// Available toolkits include: gmail, slack, notion, hubspot, salesforce, etc.
-```
-</CodeGroup>
-
-**Popular Toolkits:**
-
-- **GitHub**: Repository management, issues, PRs
-- **Gmail**: Email sending, reading, searching
-- **Slack**: Messaging, channels, user management
-- **Google Calendar**: Event management, scheduling
-- **Notion**: Database operations, page creation
-
-[**→ Explore Tools & Toolkits**](./tools-and-toolkits)
-
-
-### 4. **Connected Accounts** - User Authorizations
-
-Connected Accounts represent a user's authorized connection to an external service. Users must authorize access before tools can act on their behalf.
-
-<CodeGroup>
-```python Python
-# User authorizes GitHub access
-connection_request = await composio.connected_accounts.initiate('user_123', 'ac_authconfig_id')
-
-# After user completes OAuth flow
-connected_account = await composio.connected_accounts.wait_for_connection(connection_request.id)
-
-# Now tools can access user's GitHub data
-repos = await composio.tools.execute('GITHUB_LIST_REPOS',
- user_id='user_123',
- connected_account_id=connected_account.id
-)
-```
-
-```typescript TypeScript
-// User authorizes GitHub access
-const connectionRequest = await composio.connectedAccounts.initiate('user_123', 'ac_authconfig_id');
-
-// After user completes OAuth flow
-const connectedAccount = await composio.connectedAccounts.waitForConnection(connectionRequest.id);
-
-// Now tools can access user's GitHub data
-const repos = await composio.tools.execute('GITHUB_LIST_REPOS', {
- userId: 'user_123',
- connectedAccountId: connectedAccount.id,
-});
-```
-</CodeGroup>
-
-**Connection Types:**
-
-- **OAuth2**: Most common (GitHub, Google, Slack)
-- **API Keys**: For services like OpenAI, Anthropic
-- **Basic Auth**: Username/password authentication
-- **Custom**: Service-specific authentication methods
-
-[**→ Learn about Connected Accounts**](./connected-accounts)
-
-
-### 5. **Auth Configs** - Authentication Templates
-
-Auth Configs define how authentication works for each toolkit. They specify the authentication method and required credentials.
-
-<CodeGroup>
-```python Python
-# Create a custom auth config for GitHub
-auth_config = await composio.auth_configs.create('github', {
- 'type': 'use_composio_managed_auth',
- 'name': 'My GitHub Integration'
-})
-```
-
-```typescript TypeScript
-// Create a custom auth config for GitHub
-const authConfig = await composio.authConfigs.create('github', {
- type: 'use_composio_managed_auth',
- name: 'My GitHub Integration',
-});
-```
-</CodeGroup>
-
-**Auth Config Types:**
-
-- **Composio Managed**: Composio handles OAuth apps and credentials
-- **User Credentials**: Users provide their own API keys/credentials
-- **Custom Auth**: Custom authentication flows
-- **No Auth**: For public APIs that don't require authentication
-
-[**→ Understanding Auth Configs**](./auth-configs)
-
-
-### 6. **Providers** - AI Platform Integration
-
-Providers adapt Composio tools for different AI platforms, handling the formatting and execution patterns each platform expects.
-
-<CodeGroup>
-```python Python
-from composio.providers.openai import OpenAIProvider
-from composio.providers.langchain import LangChainProvider
-
-# OpenAI Provider (non-agentic)
-openai_composio = Composio(
- provider=OpenAIProvider()
-)
-
-# LangChain Provider (agentic)
-langchain_composio = Composio(
- provider=LangChainProvider()
-)
-```
-
-```typescript TypeScript
-import { OpenAIProvider } from '@composio/openai';
-import { LangChainProvider } from '@composio/langchain';
-
-// OpenAI Provider (non-agentic)
-const openaiComposio = new Composio({
- provider: new OpenAIProvider(),
-});
-
-// LangChain Provider (agentic)
-const langchainComposio = new Composio({
- provider: new LangChainProvider(),
-});
-```
-</CodeGroup>
-
-**Provider Types:**
-
-- **Non-Agentic**: Format tools for external use (OpenAI, Anthropic, Google)
-- **Agentic**: Control tool execution internally (LangChain, Vercel AI)
-
-[**→ Learn about Providers**](./providers)
-
-## How It All Works Together
-
-Here's how these concepts work together in a typical application:
-
-### 1. **Setup Phase**
-
-<CodeGroup>
-```typescript TypeScript
-// Initialize with your preferred provider
-const composio = new Composio({
- apiKey: process.env.COMPOSIO_API_KEY,
- provider: new OpenAIProvider(),
-});
-```
-
-```python Python
-# Initialize with your preferred provider
-composio = Composio(
- api_key=os.environ.get('COMPOSIO_API_KEY'),
- provider=OpenAIProvider()
-)
-```
-</CodeGroup>
-
-### 2. **User Onboarding**
-
-<CodeGroup>
-```typescript TypeScript
-// When a user wants to connect GitHub
-const connectionRequest = await composio.connectedAccounts.initiate(
- user.id, // Your user's ID
- 'ac_123322' // Auth config ID to connect
-);
-
-// User completes OAuth flow in browser
-// Connection is established automatically
-```
-
-```python Python
-# When a user wants to connect GitHub
-connection_request = await composio.connected_accounts.initiate(
- user.id, # Your user's ID
- 'ac_123322' # Auth config ID to connect
-)
-
-# User completes OAuth flow in browser
-# Connection is established automatically
-```
-</CodeGroup>
-
-### 3. **Tool Execution**
-
-<CodeGroup>
-```typescript TypeScript
-// Execute tools on behalf of the user
-const result = await composio.tools.execute('GITHUB_CREATE_ISSUE', {
- userId: user.id,
- arguments: {
- owner: 'myorg',
- repo: 'myrepo',
- title: 'Bug Report',
- body: 'Description of the bug...',
- },
-});
-```
-
-```python Python
-# Execute tools on behalf of the user
-result = await composio.tools.execute('GITHUB_CREATE_ISSUE',
- user_id=user.id,
- arguments={
- 'owner': 'myorg',
- 'repo': 'myrepo',
- 'title': 'Bug Report',
- 'body': 'Description of the bug...'
- }
-)
-```
-</CodeGroup>
-
-### 4. **AI Integration**
-
-<CodeGroup>
-```typescript TypeScript
-// Use tools with AI models
-const tools = await composio.tools.get(user.id, {
- toolkits: ['github', 'slack'],
-});
-
-const completion = await openai.chat.completions.create({
- model: 'gpt-4',
- messages: [{ role: 'user', content: 'Create a GitHub issue and notify the team on Slack' }],
- tools: tools, // Composio tools formatted for OpenAI
-});
-```
-
-```python Python
-# Use tools with AI models
-tools = await composio.tools.get(user.id,
- toolkits=['github', 'slack']
-)
-
-completion = await openai.chat.completions.create(
- model='gpt-4',
- messages=[{'role': 'user', 'content': 'Create a GitHub issue and notify the team on Slack'}],
- tools=tools # Composio tools formatted for OpenAI
-)
-```
-</CodeGroup>
-
-## Key Patterns and Best Practices
-
-### 1. **User-Centric Design**
-
-<CodeGroup>
-```typescript TypeScript
-// ✅ Always scope operations to specific users
-const userTools = await composio.tools.get(userId, { toolkits: ['github'] });
-
-// ❌ Don't use 'default' in production
-const defaultTools = await composio.tools.get('default', { toolkits: ['github'] });
-```
-
-```python Python
-# ✅ Always scope operations to specific users
-user_tools = await composio.tools.get(user_id, toolkits=['github'])
-
-# ❌ Don't use 'default' in production
-default_tools = await composio.tools.get('default', toolkits=['github'])
-```
-</CodeGroup>
-
-### 2. **Error Handling**
-
-<CodeGroup>
-```typescript TypeScript
-try {
- const result = await composio.tools.execute('GITHUB_GET_REPO', {
- userId: user.id,
- arguments: { owner: 'composio', repo: 'sdk' },
- });
-
- if (result.successful) {
- // Handle success
- } else {
- // Handle tool-level errors
- console.error('Tool error:', result.error);
- }
-} catch (error) {
- // Handle SDK-level errors
- console.error('SDK error:', error.message);
-}
-```
-
-```python Python
-try:
- result = await composio.tools.execute('GITHUB_GET_REPO',
- user_id=user.id,
- arguments={'owner': 'composio', 'repo': 'sdk'}
- )
-
- if result.successful:
- # Handle success
- pass
- else:
- # Handle tool-level errors
- print('Tool error:', result.error)
-except Exception as error:
- # Handle SDK-level errors
- print('SDK error:', str(error))
-```
-</CodeGroup>
-
-### 3. **Connection Management**
-
-<CodeGroup>
-```typescript TypeScript
-// Check if user has required connections
-const accounts = await composio.connectedAccounts.list({
- userIds: [userId],
- toolkitSlugs: ['github'],
-});
-
-if (accounts.items.length === 0) {
- // Prompt user to connect GitHub
- const connection = await composio.toolkits.authorize(userId, 'github');
- // Redirect to connection.redirectUrl
-}
-```
-
-```python Python
-# Check if user has required connections
-accounts = await composio.connected_accounts.list(
- user_ids=[user_id],
- toolkit_slugs=['github']
-)
-
-if len(accounts.items) == 0:
- # Prompt user to connect GitHub
- connection = await composio.toolkits.authorize(user_id, 'github')
- # Redirect to connection.redirect_url
-```
-</CodeGroup>
-
-## Advanced Concepts
-
-### Custom Tools
-
-Create your own tools for services not yet supported:
-
-<CodeGroup>
-```typescript TypeScript
-const customTool = await composio.tools.createCustomTool({
- slug: 'MY_CUSTOM_TOOL',
- name: 'My Custom Tool',
- description: 'Does something specific',
- inputParameters: z.object({
- // Define the input parameters for the tool
- param1: z.string().describe('The first parameter'),
- param2: z.string().describe('The second parameter'),
- }),
- execute: async params => {
- // Your custom logic
- return { data: {}, successful: true, error: null };
- },
-});
-```
-
-```python Python
-custom_tool = await composio.tools.create_custom_tool(
- slug='MY_CUSTOM_TOOL',
- name='My Custom Tool',
- description='Does something specific',
- input_parameters=z.object({
- # Define the input parameters for the tool
- 'param1': z.string().describe('The first parameter'),
- 'param2': z.string().describe('The second parameter')
- }),
- execute=lambda params: {
- # Your custom logic
- 'data': {},
- 'successful': True,
- 'error': None
- }
-)
-```
-</CodeGroup>
-
-### MCP (Model Control Protocol)
-
-Expose tools to AI models through a standardized protocol:
-
-<CodeGroup>
-```typescript TypeScript
-const mcpServer = await composio.mcp.create('my-server', [
- {
- toolkit: 'github',
- authConfigId: 'auth_123',
- allowedTools: ['GITHUB_GET_REPO', 'GITHUB_CREATE_ISSUE'],
- },
-]);
-```
-
-```python Python
-mcp_server = await composio.mcp.create('my-server', [
- {
- 'toolkit': 'github',
- 'auth_config_id': 'auth_123',
- 'allowed_tools': ['GITHUB_GET_REPO', 'GITHUB_CREATE_ISSUE']
- }
-])
-```
-</CodeGroup>
-
-### Triggers
-
-React to real-time events from external services:
-
-<CodeGroup>
-```typescript TypeScript
-composio.triggers.subscribe(
- event => {
- console.log('New email received:', event.payload);
- },
- {
- toolkits: ['gmail'],
- triggerSlug: ['GMAIL_NEW_EMAIL'],
- }
-);
-```
-
-```python Python
-def handle_event(event):
- print('New email received:', event.payload)
-
-composio.triggers.subscribe(
- handle_event,
- toolkits=['gmail'],
- trigger_slug=['GMAIL_NEW_EMAIL']
-)
-```
-</CodeGroup>
-
-## Quick Reference
-
-| Concept | Purpose | Example |
-| --------------------- | ------------------- | ------------------- |
-| **User ID** | Identity & security | `'user_123'` |
-| **Tool** | Specific action | `'GITHUB_GET_REPO'` |
-| **Toolkit** | Service collection | `'github'` |
-| **Connected Account** | User authorization | OAuth to GitHub |
-| **Auth Config** | Auth template | GitHub OAuth app |
-| **Provider** | AI integration | OpenAI, LangChain |
-
-## Common Questions
-
-**Q: Can one user have multiple connected accounts for the same service?**
-A: Yes, but it requires explicitly allowing multiple connections when creating them.
-
-**Q: Do I need to store authentication tokens?**
-A: No, Composio manages all tokens securely. You only work with Connected Account IDs.
-
-**Q: Can I use tools without user authentication?**
-A: Some tools (like HackerNews) don't require authentication, but most do.
-
-**Q: How do I know which tools require authentication?**
-A: Tools that require authentication will throw an error if no connected account is provided.
-
-
-**💡 Remember**: These concepts work together to provide a secure, scalable, and flexible way to integrate external services into your applications. Start with the basics and gradually explore advanced features as your needs grow.
diff --git a/fern/pages/src/core-concepts/tools-and-toolkits.mdx b/fern/pages/src/core-concepts/tools-and-toolkits.mdx
deleted file mode 100644
index 1d5d227f7..000000000
--- a/fern/pages/src/core-concepts/tools-and-toolkits.mdx
+++ /dev/null
@@ -1,767 +0,0 @@
----
-title: Tools and Toolkits
-subtitle: Understanding the tools and toolkits of Composio
-image: 'https://og.composio.dev/api/og?title=Tools%20and%20Toolkits' # image for socials
-keywords: ''
-hide-nav-links: false
----
-
-Tools and Toolkits form the core functionality of Composio, enabling your applications to interact with external services. Understanding the distinction between these concepts and how to use them effectively is essential for building robust integrations.
-
-## Understanding the Hierarchy
-
-### Tools: Individual Actions
-
-A **Tool** represents a single, specific action that can be performed with an external service. Each tool has:
-
-- **Unique Slug**: A standardized identifier (e.g., `GITHUB_GET_REPO`)
-- **Input Parameters**: The data required to execute the tool
-- **Output Schema**: The structure of data returned
-- **Authentication Requirements**: Whether user authorization is needed
-
-<CodeGroup>
-```python Python
-# Example: Getting repository information
-result = composio.tools.execute('GITHUB_GET_REPO',
- user_id='user_123',
- arguments={
- 'owner': 'composiohq',
- 'repo': 'composio'
- }
-)
-
-# The tool returns structured data
-
-print(result.data.name) // "sdk"
-print(result.data.description) // Repository description
-print(result.data.stargazers_count) // Number of stars
-
-````
-
-```typescript TypeScript
-// Example: Getting repository information
-const result = await composio.tools.execute('GITHUB_GET_REPO', {
- userId: 'user_123',
- arguments: {
- owner: 'composiohq',
- repo: 'composio'
- }
-});
-
-// The tool returns structured data
-console.log(result.data.name); // "sdk"
-console.log(result.data.description); // Repository description
-console.log(result.data.stargazers_count); // Number of stars
-````
-
-</CodeGroup>
-
-### Toolkits: Service/App Collections
-
-A **Toolkit** is a collection of related tools that work with the same external service. For example:
-
-- **GitHub Toolkit**: Contains tools for repositories, issues, pull requests, users, organizations
-- **Gmail Toolkit**: Contains tools for reading, sending, searching emails
-- **Slack Toolkit**: Contains tools for messaging, channels, user management
-
-<CodeGroup>
-```python Python
-# Get all tools from the GitHub toolkit
-github_tools = composio.tools.get('user_123',
- toolkits=['github']
-)
-
-print(f"GitHub toolkit contains {len(github_tools)} tools")
-
-# Outputs: GitHub toolkit contains 45+ tools
-
-````
-
-```typescript TypeScript
-// Get all tools from the GitHub toolkit
-const githubTools = await composio.tools.get('user_123', {
- toolkits: ['github']
-});
-
-console.log(`GitHub toolkit contains ${githubTools.length} tools`);
-// Outputs: GitHub toolkit contains 45+ tools
-````
-
-</CodeGroup>
-
-## Tool Anatomy
-
-### Tool Structure
-
-Every tool follows a consistent structure:
-
-<CodeGroup>
-```json JSON
-{
- "slug": "GITHUB_GET_REPO",
- "name": "Get Repository",
- "description": "Retrieve information about a specific GitHub repository",
- "inputParameters": {
- "type": "object",
- "properties": {
- "owner": {
- "type": "string",
- "description": "Repository owner username or organization name"
- },
- "repo": {
- "type": "string",
- "description": "Repository name"
- }
- },
- "required": ["owner", "repo"]
- },
- "outputParameters": {
- "type": "object",
- "properties": {
- "name": { "type": "string" },
- "description": { "type": "string" },
- "stargazers_count": { "type": "integer" },
- "html_url": { "type": "string" }
- }
- }
-}
-```
-</CodeGroup>
-
-### Tool Categories
-
-Tools can be categorized by their authentication requirements:
-
-**Public Tools** - No authentication required:
-
-<CodeGroup>
-```python Python
-# HackerNews tools work without user authentication
-user = await composio.tools.execute('HACKERNEWS_GET_USER',
- user_id='default',
- arguments={'user_id': 'pg'}
-)
-```
-
-```typescript TypeScript
-// HackerNews tools work without user authentication
-const user = await composio.tools.execute('HACKERNEWS_GET_USER', {
- userId: 'default',
- arguments: { userId: 'pg' },
-});
-```
-
-</CodeGroup>
-
-**Authenticated Tools** - Require user authorization:
-
-<CodeGroup>
-```python Python
-# GitHub tools require connected account
-repos = await composio.tools.execute('GITHUB_LIST_REPOS',
- user_id='user_123',
- connected_account_id='ca_github_abc123',
- arguments={'per_page': 10}
-)
-```
-
-```typescript TypeScript
-// GitHub tools require connected account
-const repos = await composio.tools.execute('GITHUB_LIST_REPOS', {
- userId: 'user_123',
- connectedAccountId: 'ca_github_abc123',
- arguments: { per_page: 10 },
-});
-```
-
-</CodeGroup>
-
-## Working with Tools
-
-### Discovering Available Tools
-
-**List tools by Toolkit:**
-
-<CodeGroup>
-
-```python Python
-# Get tools from specific toolkits
-tools = await composio.tools.get('user_123',
- toolkits=['github', 'gmail']
-)
-```
-
-```typescript TypeScript
-// Get tools from specific toolkits
-const tools = await composio.tools.get('user_123', {
- toolkits: ['github', 'gmail'],
-});
-```
-
-</CodeGroup>
-
-**Search for Tools:**
-
-<CodeGroup>
-
-```python Python
-# Search tools by name or description
-search_results = composio.tools.get('user_123',
- search='repository',
- limit=10
-)
-```
-
-```typescript TypeScript
-// Search tools by name or description
-const searchResults = await composio.tools.get('user_123', {
- search: 'repository',
- limit: 10,
-});
-```
-
-</CodeGroup>
-
-**Get Specific Tools:**
-
-<CodeGroup>
-
-```python Python
-# Get specific tools by their slugs
-specific_tools = await composio.tools.get('user_123',
- tools=['GITHUB_GET_REPO', 'GITHUB_CREATE_ISSUE', 'GMAIL_SEND_EMAIL']
-)
-```
-
-```typescript TypeScript
-// Get specific tools by their slugs
-const specificTools = await composio.tools.get('user_123', {
- tools: ['GITHUB_GET_REPO', 'GITHUB_CREATE_ISSUE', 'GMAIL_SEND_EMAIL'],
-});
-```
-
-</CodeGroup>
-
-### Tool Execution Patterns
-
-**Basic Execution:**
-
-<CodeGroup>
-
-```python Python
-try:
- result = await composio.tools.execute('GITHUB_GET_REPO',
- user_id='user_123',
- arguments={
- 'owner': 'composio',
- 'repo': 'sdk'
- }
- )
-
- if result.successful:
- print('Repository data:', result.data)
- else:
- print('Tool execution failed:', result.error)
-except Exception as error:
- print('SDK error:', str(error))
-```
-
-```typescript TypeScript
-try {
- const result = await composio.tools.execute('GITHUB_GET_REPO', {
- userId: 'user_123',
- arguments: {
- owner: 'composio',
- repo: 'sdk',
- },
- });
-
- if (result.successful) {
- console.log('Repository data:', result.data);
- } else {
- console.error('Tool execution failed:', result.error);
- }
-} catch (error) {
- console.error('SDK error:', error.message);
-}
-```
-
-</CodeGroup>
-
-**With Connected Account:**
-
-<CodeGroup>
-```python Python
-# For tools requiring authentication
-result = composio.tools.execute('GITHUB_CREATE_ISSUE',
- user_id='user_123',
- connected_account_id='ca_abc123',
- arguments={
- 'owner': 'myorg',
- 'repo': 'myrepo',
- 'title': 'Bug Report',
- 'body': 'Description of the issue...'
- }
-)
-```
-
-```typescript TypeScript
-// For tools requiring authentication
-const result = await composio.tools.execute('GITHUB_CREATE_ISSUE', {
- userId: 'user_123',
- connectedAccountId: 'ca_abc123',
- arguments: {
- owner: 'myorg',
- repo: 'myrepo',
- title: 'Bug Report',
- body: 'Description of the issue...',
- },
-});
-```
-
-</CodeGroup>
-
-## Toolkit Authentication Patterns
-
-### OAuth2 Toolkits
-
-Most modern services use OAuth2 for secure authentication:
-
-<CodeGroup>
-```python Python
-# Initiate OAuth flow
-connection_request = await composio.toolkits.authorize('user_123', 'github')
-
-# User visits connection_request.redirect_url to authorize
-
-# After authorization, get the connected account
-
-connected_account = await composio.connected_accounts.wait_for_connection(
-connection_request.id
-)
-
-# Use the connected account with toolkit tools
-
-result = await composio.tools.execute('GITHUB_GET_REPO',
-user_id='user_123',
-connected_account_id=connected_account.id,
-arguments={'owner': 'composio', 'repo': 'sdk'}
-)
-
-````
-```typescript TypeScript
-// Initiate OAuth flow
-const connectionRequest = await composio.toolkits.authorize('user_123', 'github');
-
-// User visits connectionRequest.redirectUrl to authorize
-// After authorization, get the connected account
-const connectedAccount = await composio.connectedAccounts.waitForConnection(
-connectionRequest.id
-);
-
-// Use the connected account with toolkit tools
-const result = await composio.tools.execute('GITHUB_GET_REPO', {
-userId: 'user_123',
-connectedAccountId: connectedAccount.id,
-arguments: { owner: 'composio', repo: 'sdk' }
-});
-
-````
-
-</CodeGroup>
-
-### API Key Toolkits
-
-Some services use API keys for authentication:
-
-```typescript TypeScript
-// Connect using API key
-const connectionRequest = await composio.connectedAccounts.initiate('user_123', 'auth_config_id', {
- config: AuthScheme.ApiKey({
- api_key: 'user_provided_api_key',
- }),
-});
-```
-
-<CodeGroup>
-
-```python Python
-# Connect using API key
-connection_request = await composio.connected_accounts.initiate(
- 'user_123',
- 'auth_config_id',
- config=AuthScheme.api_key(
- api_key='user_provided_api_key'
- )
-)
-```
-
-```typescript TypeScript
-// Connect using API key
-const connectionRequest = await composio.connectedAccounts.initiate('user_123', 'auth_config_id', {
- config: AuthScheme.ApiKey({
- api_key: 'user_provided_api_key',
- }),
-});
-```
-
-</CodeGroup>
-
-### No Authentication Required
-
-Some toolkits provide public data without authentication:
-
-<CodeGroup>
-
-```python
-# Public tools work without connected accounts
-result = await composio.tools.execute('HACKERNEWS_GET_USER',
- user_id='default',
- arguments={'user_id': 'pg'}
-)
-```
-
-```typescript TypeScript
-// Public tools work without connected accounts
-const result = await composio.tools.execute('HACKERNEWS_GET_USER', {
- userId: 'default',
- arguments: { userId: 'pg' },
-});
-```
-
-</CodeGroup>
-
-## Advanced Tool Features
-
-### Tool Parameters and Validation
-
-Tools automatically validate input parameters:
-
-<CodeGroup>
-
-```python Python
-# This will fail validation
-try:
- await composio.tools.execute('GITHUB_GET_REPO',
- user_id='user_123',
- arguments={
- 'owner': 'composio'
- // Missing required 'repo' parameter
- }
- )
-except Exception as error:
- print('Validation error:', str(error))
- // Error: Missing required parameter 'repo'
-```
-
-```typescript TypeScript
-// This will fail validation
-try {
- await composio.tools.execute('GITHUB_GET_REPO', {
- userId: 'user_123',
- arguments: {
- owner: 'composio',
- // Missing required 'repo' parameter
- },
- });
-} catch (error) {
- console.error('Validation error:', error.message);
- // Error: Missing required parameter 'repo'
-}
-```
-
-</CodeGroup>
-
-### File Handling
-
-Some tools support file operations:
-
-<CodeGroup>
-
-```python Python
-# Tools with file upload capability
-result = await composio.tools.execute('GOOGLE_DRIVE_UPLOAD_FILE',
- user_id='user_123',
- arguments={
- 'file_to_upload': '/path/to/local/file.pdf' // SDK handles upload automatically
- }
-)
-
-# Tools that return files
-file_result = await composio.tools.execute('GOOGLE_DRIVE_DOWNLOAD_FILE',
- user_id='user_123',
- arguments={'file_id': 'file_id'}
-)
-
-# SDK automatically downloads file to local path
-print('Downloaded to:', file_result.data.file.uri)
-```
-```typescript TypeScript
-// Tools with file upload capability
-const result = await composio.tools.execute('GOOGLE_DRIVE_UPLOAD_FILE', {
- userId: 'user_123',
- arguments: {
- file_to_upload: '/path/to/local/file.pdf', // SDK handles upload automatically
- }
-});
-
-// Tools that return files
-const fileResult = await composio.tools.execute('GOOGLE_DRIVE_DOWNLOAD_FILE', {
-userId: 'user_123',
-arguments: { file_id: 'file_id' }
-});
-
-// SDK automatically downloads file to local path
-console.log('Downloaded to:', fileResult.data.file.uri);
-
-```
-
-</CodeGroup>
-
-### Error Handling Patterns
-
-Different types of errors require different handling approaches:
-
-
-<CodeGroup>
-```python Python
-async def execute_tool_safely(tool_slug: str, params: dict):
- try:
- result = await composio.tools.execute(tool_slug, **params)
-
- if result.successful:
- return result.data
- else:
- # Tool-level error (e.g., API rate limit, invalid parameters)
- raise ToolExecutionError(result.error)
- except ComposioToolNotFoundError:
- # Tool doesn't exist
- print('Tool not found:', tool_slug)
- raise
- except ComposioConnectedAccountNotFoundError:
- # User hasn't connected the required account
- print('Account not connected for toolkit')
- raise
- except Exception as error:
- # Other SDK errors
- print('Unexpected error:', str(error))
- raise
-```
-
-```typescript TypeScript
-async function executeToolSafely(toolSlug: string, params: Record<string, any>) {
- try {
- const result = await composio.tools.execute(toolSlug, params);
-
- if (result.successful) {
- return result.data;
- } else {
- // Tool-level error (e.g., API rate limit, invalid parameters)
- throw new ToolExecutionError(result.error);
- }
- } catch (error) {
- if (error instanceof ComposioToolNotFoundError) {
- // Tool doesn't exist
- console.error('Tool not found:', toolSlug);
- } else if (error instanceof ComposioConnectedAccountNotFoundError) {
- // User hasn't connected the required account
- console.error('Account not connected for toolkit');
- } else {
- // Other SDK errors
- console.error('Unexpected error:', error);
- }
- throw error;
- }
-}
-```
-
-</CodeGroup>
-
-## Tool Discovery and Documentation
-
-### Exploring Toolkit Capabilities
-
-<CodeGroup>
-
-```python Python
-# Get toolkit information
-toolkit = await composio.toolkits.get('github')
-print(f"{toolkit.name} has {toolkit.meta.tools_count} tools")
-
-# List all tools in a toolkit
-tools = await composio.tools.get('user_123',
- toolkits=['github']
-)
-
-for tool in tools:
- print(f"{tool.function.name}: {tool.function.description}")
-```
-```typescript TypeScript
-// Get toolkit information
-const toolkit = await composio.toolkits.get('github');
-console.log(`${toolkit.name} has ${toolkit.meta.toolsCount} tools`);
-
-// List all tools in a toolkit
-const tools = await composio.tools.get('user_123', {
-toolkits: ['github']
-});
-
-tools.forEach(tool => {
-console.log(`${tool.function.name}: ${tool.function.description}`);
-});
-
-```
-
-</CodeGroup>
-
-### Understanding Tool Requirements
-
-<CodeGroup>
-
-```python Python
-# Get detailed tool information
-tool = await composio.tools.get_raw_composio_tool_by_slug('GITHUB_GET_REPO')
-print('Required parameters:', tool.input_parameters.required)
-print('All parameters:', list(tool.input_parameters.properties.keys()))
-```
-```typescript TypeScript
-// Get detailed tool information
-const tool = await composio.tools.getRawComposioToolBySlug('GITHUB_GET_REPO');
-console.log('Required parameters:', tool.inputParameters.required);
-console.log('All parameters:', Object.keys(tool.inputParameters.properties));
-```
-
-</CodeGroup>
-
-## Integration with AI Providers
-
-Tools are automatically formatted for different AI providers:
-
-### OpenAI Integration
-
-<CodeGroup>
-```python Python
-from openai import OpenAI
-
-openai = OpenAI(api_key=os.environ.get('OPENAI_API_KEY'))
-tools = await composio.tools.get('user_123',
- toolkits=['github']
-)
-
-completion = await openai.chat.completions.create(
- model='gpt-4',
- messages=[
- {'role': 'user', 'content': 'Get information about the composio/sdk repository'}
- ],
- tools=tools # Tools are pre-formatted for OpenAI
-)
-```
-```typescript TypeScript
-import OpenAI from 'openai';
-
-const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
-const tools = await composio.tools.get('user_123', {
-toolkits: ['github']
-});
-
-const completion = await openai.chat.completions.create({
-model: 'gpt-4',
-messages: [
-{ role: 'user', content: 'Get information about the composio/sdk repository' }
-],
-tools: tools // Tools are pre-formatted for OpenAI
-});
-
-```
-
-</CodeGroup>
-
-### LangChain Integration
-
-<CodeGroup>
-```python Python
-from composio.providers.langchain import LangChainProvider
-
-langchain_composio = Composio(
- provider=LangChainProvider()
-)
-
-tools = await langchain_composio.tools.get('user_123',
- toolkits=['github']
-)
-
-# Tools are formatted as LangChain tools
-agent = tools.create_executor(model='gpt-4')
-```
-```typescript TypeScript
-import { LangChainProvider } from '@composio/langchain';
-
-const langchainComposio = new Composio({
-provider: new LangChainProvider()
-});
-
-const tools = await langchainComposio.tools.get('user_123', {
-toolkits: ['github']
-});
-
-// Tools are formatted as LangChain tools
-const agent = tools.createExecutor({ model: 'gpt-4' });
-
-```
-</CodeGroup>
-
-## Best Practices
-
-### Tool Selection
-
-- **Be Specific**: Request only the tools you need rather than entire toolkits
-- **Use Search**: Leverage search functionality to find relevant tools
-- **Check Requirements**: Verify authentication requirements before using tools
-
-### Error Handling
-
-- **Check Success**: Always verify `result.successful` before using data
-- **Handle Missing Connections**: Gracefully handle cases where users haven't connected accounts
-- **Validate Inputs**: Ensure required parameters are provided
-
-### Performance
-
-- **Batch Operations**: Group related tool executions when possible
-- **Cache Results**: Store frequently accessed data to reduce API calls
-- **Rate Limiting**: Be aware of external service rate limits
-
-### Security
-
-- **User Context**: Always execute tools in the correct user context
-- **Parameter Validation**: Validate user inputs before passing to tools
-- **Error Information**: Be careful not to expose sensitive error details to end users
-
-## Troubleshooting Common Issues
-
-### Authentication Errors
-
-```javascript
-// Check if user has connected the required toolkit
-const accounts = await composio.connectedAccounts.list({
- userIds: ['user_123'],
- toolkitSlugs: ['github'],
-});
-
-if (accounts.items.length === 0) {
- // User needs to connect GitHub
- const connection = await composio.toolkits.authorize('user_123', 'github');
-}
-```
-
-### Parameter Validation Errors
-
-```javascript
-// Get tool schema to understand required parameters
-const tool = await composio.tools.getRawComposioToolBySlug('GITHUB_GET_REPO');
-console.log('Required parameters:', tool.inputParameters.required);
-console.log('Parameter schemas:', tool.inputParameters.properties);
-```
-
----
-
-Understanding tools and toolkits is fundamental to building effective integrations with Composio. These concepts provide the building blocks for connecting your applications to the external services your users need.
diff --git a/fern/pages/src/core-concepts/triggers.mdx b/fern/pages/src/core-concepts/triggers.mdx
deleted file mode 100644
index 240a0a145..000000000
--- a/fern/pages/src/core-concepts/triggers.mdx
+++ /dev/null
@@ -1,234 +0,0 @@
----
-title: Triggers
-subtitle: Understanding the triggers in Composio
-image: 'https://og.composio.dev/api/og?title=Triggers' # image for socials
-keywords: ''
-hide-nav-links: false
----
-
-Triggers enable your applications to respond to real-time events from external services. Instead of polling for changes, triggers deliver events instantly when they occur.
-
-## What Are Triggers?
-
-A **Trigger** is a real-time event notification from an external service. When something happens in a connected service (like a new email, GitHub issue, or Slack message), Composio delivers that event to your application.
-
-<CodeGroup>
-
-```python
-# Create a trigger for new GitHub issues
-trigger = await composio.triggers.create(
- user_id='user_123',
- trigger_slug='GITHUB_ISSUE_CREATED',
- trigger_config={
- 'repository': 'composiohq/composio'
- }
-)
-```
-```typescript
-// Create a trigger for new GitHub issues
-const trigger = await composio.triggers.create(
- 'user_123',
- 'GITHUB_ISSUE_CREATED',
- {
- triggerConfig: {
- repository: 'composiohq/composio'
- }
- }
-);
-```
-
-</CodeGroup>
-
-## How Triggers Work
-
-1. **Create**: Set up a trigger for specific events
-2. **Connect**: User authorizes the external service
-3. **Monitor**: Composio watches for events in real-time
-4. **Deliver**: Events are sent to your application via webhooks or SDK
-
-## Development vs Production
-
-### Development: SDK Subscription
-For testing and development, subscribe to events in your code:
-
-<CodeGroup>
-
-
-```python
-# Development only - not for production
-def handle_event(trigger_data):
- print(f"Event: {trigger_data.trigger_slug}")
- print(f"Data: {trigger_data.payload}")
-
-composio.triggers.subscribe(
- callback=handle_event,
- filters={'user_id': 'user_123'}
-)
-```
-```typescript
-// Development only - not for production
-composio.triggers.subscribe((triggerData) => {
- console.log(`Event: ${triggerData.triggerSlug}`);
- console.log(`Data: ${triggerData.payload}`);
-}, {
- userId: 'user_123'
-});
-```
-</CodeGroup>
-
-### Production: Webhook Endpoints
-For production, use webhook endpoints to receive events:
-
-<CodeGroup>
-```python Python
-# Production webhook endpoint
[email protected]('/webhooks/composio', methods=['POST'])
-def handle_webhook():
- trigger_data = request.json
-
- # Process the event
- process_event(trigger_data)
-
- return jsonify({'status': 'success'}), 200
-```
-
-```typescript TypeScript
-// Production webhook endpoint
-app.post('/webhooks/composio', (req, res) => {
- const triggerData = req.body;
-
- // Process the event
- processEvent(triggerData);
-
- res.status(200).json({ status: 'success' });
-});
-```
-</CodeGroup>
-
-## Event Structure
-
-All trigger events follow a consistent format:
-
-<CodeGroup>
-```python Python
-# Trigger event structure
-{
- 'id': 'trigger_instance_id',
- 'trigger_slug': 'GITHUB_ISSUE_CREATED',
- 'toolkit_slug': 'github',
- 'user_id': 'user_123',
- 'payload': {
- # Event-specific data
- 'title': 'Bug Report',
- 'number': 42,
- 'author': 'username'
- },
- 'metadata': {
- 'connected_account': {
- 'id': 'ca_abc123',
- 'status': 'ACTIVE'
- }
- }
-}
-```
-
-```typescript TypeScript
-// Trigger event structure
-interface TriggerEvent {
- id: string; // Trigger instance ID
- triggerSlug: string; // Event type
- toolkitSlug: string; // Service name
- userId: string; // User ID
- payload: { // Event data
- title: string;
- number: number;
- author: string;
- };
- metadata: {
- connectedAccount: {
- id: string; // Connected account ID
- status: string; // Connection status
- };
- };
-}
-```
-</CodeGroup>
-
-## Managing Triggers
-
-### List Active Triggers
-<CodeGroup>
-
-
-```python
-# Get all active triggers
-triggers = await composio.triggers.list_active()
-
-# Filter by user or toolkit
-user_triggers = await composio.triggers.list_active(
- filters={'user_ids': ['user_123']}
-)
-```
-```typescript
-// Get all active triggers
-const triggers = await composio.triggers.listActive();
-
-// Filter by user or toolkit
-const userTriggers = await composio.triggers.listActive({
- connectedAccountIds: ['ca_123']
-});
-```
-</CodeGroup>
-
-### Enable/Disable Triggers
-<CodeGroup>
-
-
-```python
-# Temporarily disable a trigger
-await composio.triggers.disable('trigger_id')
-
-# Re-enable when needed
-await composio.triggers.enable('trigger_id')
-```
-```typescript
-// Temporarily disable a trigger
-await composio.triggers.disable('trigger_id');
-
-// Re-enable when needed
-await composio.triggers.enable('trigger_id');
-```
-</CodeGroup>
-
-## Key Differences: Development vs Production
-
-| Aspect | Development (SDK) | Production (Webhooks) |
-|--------|------------------|----------------------|
-| **Connection** | Persistent WebSocket | HTTP requests |
-| **Scalability** | Single instance | Horizontally scalable |
-| **Reliability** | Can disconnect | Built-in retries |
-| **Deployment** | Not recommended | Production-ready |
-
-## Best Practices
-
-### For Development
-- Use `triggers.subscribe()` for quick testing
-- Monitor connection status during development
-- Handle events synchronously for debugging
-
-### For Production
-- Always use webhook endpoints
-- Implement signature verification for security
-- Handle duplicate events (idempotency)
-- Use proper HTTP status codes (200 for success)
-- Implement retry logic for failed processing
-
-### General Guidelines
-- Filter events to reduce unnecessary processing
-- Monitor trigger health and connection status
-- Handle connection failures gracefully
-- Log events for debugging and monitoring
-
----
-
-Triggers enable reactive applications that respond immediately to external events, creating more efficient and responsive integrations.
\ No newline at end of file
diff --git a/fern/pages/src/core-concepts/user-ids.mdx b/fern/pages/src/core-concepts/user-ids.mdx
deleted file mode 100644
index 7bd2e7265..000000000
--- a/fern/pages/src/core-concepts/user-ids.mdx
+++ /dev/null
@@ -1,832 +0,0 @@
----
-title: User IDs - The Security Foundation
-subtitle: Understanding the security foundation of Composio
-image: 'https://og.composio.dev/api/og?title=User%20IDs' # image for socials
-keywords: ''
-hide-nav-links: true
----
-User IDs are the **core foundation** of accessing and executing tools in Composio. Every tool execution, connection authorization, and account management operation requires a `userId` parameter that identifies which user's context the operation should be performed in.
-
-## Why User IDs Are Critical
-
-User IDs provide the fundamental security layer that ensures:
-
-- **Data Isolation**: Users can only access their own connected accounts and data
-- **Security Boundaries**: No unauthorized access to other users' external services
-- **Multi-Tenancy**: Support for applications with multiple users
-- **Compliance**: Meet data privacy and security requirements
-- **Audit Trail**: Track which user performed which actions
-
-<CodeGroup>
-```python Python
-# ✅ Each user operates in their own secure context
-user_a_repos = composio.tools.execute('GITHUB_LIST_REPOS',
- user_id='user_a', # User A's GitHub repositories
- arguments={}
-)
-
-user_b_repos = composio.tools.execute('GITHUB_LIST_REPOS',
- user_id='user_b', # User B's GitHub repositories
- arguments={}
-)
-
-# User A cannot see User B's repositories, and vice versa
-```
-
-```typescript TypeScript
-// ✅ Each user operates in their own secure context
-const userARepos = await composio.tools.execute('GITHUB_LIST_REPOS', {
- userId: 'user_a', // User A's GitHub repositories
- arguments: {}
-});
-
-const userBRepos = await composio.tools.execute('GITHUB_LIST_REPOS', {
- userId: 'user_b', // User B's GitHub repositories
- arguments: {}
-});
-
-// User A cannot see User B's repositories, and vice versa
-```
-</CodeGroup>
-
-## Choosing the Right User ID
-
-### ✅ **Recommended: Database Primary Key**
-
-The best practice is to use your application's existing user identifier:
-
-<CodeGroup>
-```python Python
-# Use your database user ID
-user_id = user.id # e.g., "550e8400-e29b-41d4-a716-446655440000"
-user_id = user.uuid # e.g., UUID from your user table
-user_id = user.primary_key # Any unique, stable identifier
-
-tools = await composio.tools.get(user_id,
- toolkits=['github']
-)
-```
-
-```typescript TypeScript
-// Use your database user ID
-const userId = user.id; // e.g., "550e8400-e29b-41d4-a716-446655440000"
-const userId = user.uuid; // e.g., UUID from your user table
-const userId = user.primaryKey; // Any unique, stable identifier
-
-const tools = await composio.tools.get(userId, {
- toolkits: ['github']
-});
-```
-</CodeGroup>
-
-**Why Database IDs Are Best:**
-- **Unique**: Guaranteed uniqueness in your system
-- **Stable**: Won't change over time
-- **Consistent**: Already used throughout your application
-- **Secure**: Not guessable or enumerable
-
-### ✅ **Acceptable: Unique Username/Identifier**
-
-If you don't have database IDs, use unique, stable identifiers:
-
-<CodeGroup>
-```python Python
-user_id = user.username # e.g., "john_doe_123"
-user_id = user.external_id # e.g., "auth0|507f1f77bcf86cd799439011"
-user_id = f"tenant_{tenant_id}_user_{user_index}" # Custom format
-```
-
-```typescript TypeScript
-const userId = user.username; // e.g., "john_doe_123"
-const userId = user.externalId; // e.g., "auth0|507f1f77bcf86cd799439011"
-const userId = `tenant_${tenantId}_user_${userIndex}`; // Custom format
-```
-</CodeGroup>
-
-### ⚠️ **Avoid: Email Addresses**
-
-While functional, email addresses can change and cause issues:
-
-<CodeGroup>
-```python Python
-# Not recommended - emails can change
-user_id = user.email # e.g., "[email protected]"
-
-# Better: Use a stable ID even if you display the email
-user_id = user.id # Your stable user ID
-display_name = user.email # For display purposes only
-```
-
-```typescript TypeScript
-// Not recommended - emails can change
-const userId = user.email; // e.g., "[email protected]"
-
-// Better: Use a stable ID even if you display the email
-const userId = user.id; // Your stable user ID
-const displayName = user.email; // For display purposes only
-```
-</CodeGroup>
-
-### ❌ **Never Use: Sensitive or Guessable Data**
-
-<CodeGroup>
-```python Python
-# ❌ DON'T use sensitive information
-user_id = user.ssn # Social Security Number
-user_id = user.credit_card_number # Financial data
-
-# ❌ DON'T use easily guessable patterns
-user_id = "user1" # Sequential numbers
-user_id = "admin" # Common names
-```
-
-```typescript TypeScript
-// ❌ DON'T use sensitive information
-const userId = user.ssn; // Social Security Number
-const userId = user.creditCardNumber; // Financial data
-
-// ❌ DON'T use easily guessable patterns
-const userId = "user1"; // Sequential numbers
-const userId = "admin"; // Common names
-```
-</CodeGroup>
-
-## Organization-Based Applications
-
-For applications where users belong to organizations and apps are connected at the **organization level**, use the **organization ID** as the `userId`:
-
-### When to Use Organization IDs
-
-Use organization IDs when:
-- **Team/Organization tools**: Slack, Microsoft Teams, project management tools
-- **Enterprise applications**: IT administrators connect apps for the whole organization
-- **Shared resources**: Multiple users need access to the same connected accounts
-- **Role-based access**: Permissions are managed at the organization level
-
-### Implementation Pattern
-
-<CodeGroup>
-```python Python
-# Organization-based approach
-user_id = organization.id # e.g., "org_550e8400-e29b-41d4-a716-446655440000"
-
-# All users in the organization share the same connected accounts
-tools = await composio.tools.get(user_id,
- toolkits=['slack', 'github']
-)
-
-# Execute tools in the organization context
-result = await composio.tools.execute('SLACK_SEND_MESSAGE',
- user_id=user_id, # Organization ID, not individual user ID
- arguments={
- 'channel': '#general',
- 'text': 'Hello from the team!'
- }
-)
-```
-
-```typescript TypeScript
-// Organization-based approach
-const userId = organization.id; // e.g., "org_550e8400-e29b-41d4-a716-446655440000"
-
-// All users in the organization share the same connected accounts
-const tools = await composio.tools.get(userId, {
- toolkits: ['slack', 'github']
-});
-
-// Execute tools in the organization context
-const result = await composio.tools.execute('SLACK_SEND_MESSAGE', {
- userId: userId, // Organization ID, not individual user ID
- arguments: {
- channel: '#general',
- text: 'Hello from the team!'
- }
-});
-```
-</CodeGroup>
-
-### Complete Organization Example
-
-<CodeGroup>
-```python Python
-from composio import Composio
-
-composio = Composio(
- api_key=os.environ.get('COMPOSIO_API_KEY')
-)
-
-# 1. Admin connects Slack for the entire organization
-async def connect_organization_to_slack(organization_id: str, admin_user_id: str):
- # Use organization ID as user_id in Composio
- connection_request = await composio.toolkits.authorize(organization_id, 'slack')
-
- # Store the connection request for the admin to complete
- await store_connection_request(organization_id, admin_user_id, connection_request)
-
- return connection_request.redirect_url
-
-# 2. Any user in the organization can use the connected tools
-async def send_slack_message(organization_id: str, channel: str, message: str):
- return await composio.tools.execute('SLACK_SEND_MESSAGE',
- user_id=organization_id, # Organization ID, not individual user ID
- arguments={
- 'channel': channel,
- 'text': message
- }
- )
-
-# 3. Check if organization has required connections
-async def get_organization_tools(organization_id: str):
- return await composio.tools.get(organization_id,
- toolkits=['slack', 'github', 'jira']
- )
-
-# Usage in your API endpoint
[email protected]('/api/slack/message')
-async def send_message():
- channel = request.json['channel']
- message = request.json['message']
- organization_id = request.user.organization_id # Get from your auth system
-
- # Verify user has permission to send messages for this organization
- if not await user_can_send_messages(request.user.id, organization_id):
- return jsonify({'error': 'Insufficient permissions'}), 403
-
- try:
- result = await send_slack_message(organization_id, channel, message)
- return jsonify(result.data)
- except Exception as error:
- return jsonify({'error': 'Failed to send message'}), 500
-```
-
-```typescript TypeScript
-import { Composio } from '@composio/core';
-
-const composio = new Composio({
- apiKey: process.env.COMPOSIO_API_KEY
-});
-
-// 1. Admin connects Slack for the entire organization
-async function connectOrganizationToSlack(organizationId: string, adminUserId: string) {
- // Use organization ID as userId in Composio
- const connectionRequest = await composio.toolkits.authorize(organizationId, 'slack');
-
- // Store the connection request for the admin to complete
- await storeConnectionRequest(organizationId, adminUserId, connectionRequest);
-
- return connectionRequest.redirectUrl;
-}
-
-// 2. Any user in the organization can use the connected tools
-async function sendSlackMessage(organizationId: string, channel: string, message: string) {
- return await composio.tools.execute('SLACK_SEND_MESSAGE', {
- userId: organizationId, // Organization ID, not individual user ID
- arguments: {
- channel: channel,
- text: message
- }
- });
-}
-
-// 3. Check if organization has required connections
-async function getOrganizationTools(organizationId: string) {
- return await composio.tools.get(organizationId, {
- toolkits: ['slack', 'github', 'jira']
- });
-}
-
-// Usage in your API endpoint
-app.post('/api/slack/message', async (req, res) => {
- const { channel, message } = req.body;
- const organizationId = req.user.organizationId; // Get from your auth system
-
- // Verify user has permission to send messages for this organization
- if (!(await userCanSendMessages(req.user.id, organizationId))) {
- return res.status(403).json({ error: 'Insufficient permissions' });
- }
-
- try {
- const result = await sendSlackMessage(organizationId, channel, message);
- res.json(result.data);
- } catch (error) {
- res.status(500).json({ error: 'Failed to send message' });
- }
-});
-```
-</CodeGroup>
-
-## 🚨 The `default` User ID
-
-The `default` userId refers to the default account of your Composio project and should **only be used for**:
-
-- **Testing and development** environments
-- **Single-user applications** where external users don't connect their own accounts
-- **Internal tools** where all operations are performed by your system
-- **Learning and experimentation**
-
-### When `default` is Appropriate
-
-<CodeGroup>
-```python Python
-# ✅ Good uses for 'default'
-# 1. Development and testing
-if os.environ.get('NODE_ENV') == 'development':
- tools = await composio.tools.get('default', toolkits=['github'])
-
-# 2. Single-user applications
-single_user_app = await composio.tools.execute('HACKERNEWS_GET_USER',
- user_id='default',
- arguments={'user_id': 'pg'}
-)
-
-# 3. Internal automation scripts
-internal_script = await composio.tools.execute('GITHUB_CREATE_ISSUE',
- user_id='default',
- arguments={} # internal tool usage
-)
-```
-
-```typescript TypeScript
-// ✅ Good uses for 'default'
-// 1. Development and testing
-if (process.env.NODE_ENV === 'development') {
- const tools = await composio.tools.get('default', { toolkits: ['github'] });
-}
-
-// 2. Single-user applications
-const singleUserApp = await composio.tools.execute('HACKERNEWS_GET_USER', {
- userId: 'default',
- arguments: { userId: 'pg' }
-});
-
-// 3. Internal automation scripts
-const internalScript = await composio.tools.execute('GITHUB_CREATE_ISSUE', {
- userId: 'default',
- arguments: { /* internal tool usage */ }
-});
-```
-</CodeGroup>
-
-### When NOT to Use `default`
-
-<CodeGroup>
-```python Python
-# ❌ NEVER use 'default' in production multi-user apps
[email protected]('/api/github/repos')
-async def list_repos():
- # This would expose other users' data!
- repos = await composio.tools.execute('GITHUB_LIST_REPOS',
- user_id='default', # ❌ Wrong! Use request.user.id
- arguments={}
- )
-
-# ❌ Don't use 'default' for user-specific operations
-user_email = await composio.tools.execute('GMAIL_SEND_EMAIL',
- user_id='default', # ❌ Wrong! This could send from wrong account
- arguments={
- 'subject': 'Personal message'
- }
-)
-```
-
-```typescript TypeScript
-// ❌ NEVER use 'default' in production multi-user apps
-app.post('/api/github/repos', async (req, res) => {
- // This would expose other users' data!
- const repos = await composio.tools.execute('GITHUB_LIST_REPOS', {
- userId: 'default', // ❌ Wrong! Use req.user.id
- arguments: {}
- });
-});
-
-// ❌ Don't use 'default' for user-specific operations
-const userEmail = await composio.tools.execute('GMAIL_SEND_EMAIL', {
- userId: 'default', // ❌ Wrong! This could send from wrong account
- arguments: {
- subject: 'Personal message'
- }
-});
-```
-</CodeGroup>
-
-## Security Best Practices
-
-### 1. **Always Validate User IDs**
-
-<CodeGroup>
-```python Python
-# ✅ Validate user IDs before using them
-def validate_user_id(user_id: str, authenticated_user: Any) -> str:
- # Ensure the user can only access their own data
- if user_id != authenticated_user.id:
- raise ValueError('Unauthorized: Cannot access other user data')
- return user_id
-
[email protected]('/api/tools/execute')
-async def execute_tool():
- user_id = validate_user_id(request.json['user_id'], request.user)
-```
-
-```typescript TypeScript
-// ✅ Validate user IDs before using them
-function validateUserId(userId: string, authenticatedUser: any) {
- // Ensure the user can only access their own data
- if (userId !== authenticatedUser.id) {
- throw new Error('Unauthorized: Cannot access other user data');
- }
- return userId;
-}
-
-app.post('/api/tools/execute', async (req, res) => {
- const userId = validateUserId(req.body.userId, req.user);
- // ... proceed with execution
-});
-```
-</CodeGroup>
-
-### 2. **Integrate with Your Auth System**
-
-<CodeGroup>
-```python Python
-# ✅ Integrate with your existing auth
-def authenticate_user(request):
- token = request.headers.get('authorization')
- user = verify_jwt(token)
-
- if not user:
- return jsonify({'error': 'Unauthorized'}), 401
-
- request.user = user
- return None
-
[email protected]('/api/composio')
-def auth_middleware():
- return authenticate_user(request)
-
[email protected]('/api/composio/execute')
-async def execute_tool():
- # request.user is guaranteed to be authenticated
- result = await composio.tools.execute(request.json['tool_slug'],
- user_id=request.user.id, # Use authenticated user's ID
- arguments=request.json['arguments']
- )
-
- return jsonify(result)
-```
-
-```typescript TypeScript
-// ✅ Integrate with your existing auth
-const authenticateUser = async (req, res, next) => {
- const token = req.headers.authorization;
- const user = await verifyJWT(token);
-
- if (!user) {
- return res.status(401).json({ error: 'Unauthorized' });
- }
-
- req.user = user;
- next();
-};
-
-app.use('/api/composio', authenticateUser);
-
-app.post('/api/composio/execute', async (req, res) => {
- // req.user is guaranteed to be authenticated
- const result = await composio.tools.execute(req.body.toolSlug, {
- userId: req.user.id, // Use authenticated user's ID
- arguments: req.body.arguments
- });
-
- res.json(result);
-});
-```
-</CodeGroup>
-
-### 3. **Never Expose User IDs in Client Code**
-
-<CodeGroup>
-```python Python
-# ❌ Don't expose user IDs to the client
-client_config = {
- 'user_id': user.id, # ❌ Exposed to client
- 'api_key': 'composio-key' # ❌ Never expose API keys
-}
-
-# ✅ Keep user IDs on the server
[email protected]('/api/user/tools')
-async def get_user_tools():
- # User ID is determined server-side from authentication
- tools = await composio.tools.get(request.user.id, request.json['filters'])
- return jsonify(tools)
-```
-
-```typescript TypeScript
-// ❌ Don't expose user IDs to the client
-const clientConfig = {
- userId: user.id, // ❌ Exposed to client
- apiKey: 'composio-key' // ❌ Never expose API keys
-};
-
-// ✅ Keep user IDs on the server
-app.post('/api/user/tools', async (req, res) => {
- // User ID is determined server-side from authentication
- const tools = await composio.tools.get(req.user.id, req.body.filters);
- res.json(tools);
-});
-```
-</CodeGroup>
-
-## Implementation Examples
-
-### Express.js Application
-
-<CodeGroup>
-```python Python
-from flask import Flask, request, jsonify
-from composio import Composio
-
-app = Flask(__name__)
-composio = Composio(api_key=os.environ.get('COMPOSIO_API_KEY'))
-
-# Middleware to ensure user authentication
-def require_auth():
- if not request.user:
- return jsonify({'error': 'Authentication required'}), 401
- return None
-
-# Get user's available tools
[email protected]('/api/tools', methods=['GET'])
-@require_auth
-async def get_tools():
- try:
- tools = await composio.tools.get(request.user.id,
- toolkits=request.args.get('toolkits', '').split(',') if request.args.get('toolkits') else []
- )
- return jsonify(tools)
- except Exception as error:
- return jsonify({'error': str(error)}), 500
-
-# Execute tool for user
[email protected]('/api/tools/execute', methods=['POST'])
-@require_auth
-async def execute_tool():
- try:
- result = await composio.tools.execute(request.json['tool_slug'],
- user_id=request.user.id, # Always use authenticated user's ID
- arguments=request.json['arguments'],
- connected_account_id=request.json.get('connected_account_id')
- )
-
- return jsonify(result)
- except Exception as error:
- return jsonify({'error': str(error)}), 500
-```
-
-```typescript TypeScript
-import express from 'express';
-import { Composio } from '@composio/core';
-
-const app = express();
-const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
-
-// Middleware to ensure user authentication
-const requireAuth = (req, res, next) => {
- if (!req.user) {
- return res.status(401).json({ error: 'Authentication required' });
- }
- next();
-};
-
-// Get user's available tools
-app.get('/api/tools', requireAuth, async (req, res) => {
- try {
- const tools = await composio.tools.get(req.user.id, {
- toolkits: req.query.toolkits?.split(',') || []
- });
- res.json(tools);
- } catch (error) {
- res.status(500).json({ error: error.message });
- }
-});
-
-// Execute tool for user
-app.post('/api/tools/execute', requireAuth, async (req, res) => {
- try {
- const result = await composio.tools.execute(req.body.toolSlug, {
- userId: req.user.id, // Always use authenticated user's ID
- arguments: req.body.arguments,
- connectedAccountId: req.body.connectedAccountId
- });
-
- res.json(result);
- } catch (error) {
- res.status(500).json({ error: error.message });
- }
-});
-```
-</CodeGroup>
-
-### Next.js API Routes
-
-<CodeGroup>
-```python Python
-# pages/api/composio/tools.py
-from fastapi import FastAPI, Depends, HTTPException
-from composio import Composio
-from auth import get_server_session
-
-app = FastAPI()
-composio = Composio(api_key=os.environ.get('COMPOSIO_API_KEY'))
-
-async def get_session(request):
- session = await get_server_session(request)
- if not session or not session.user:
- raise HTTPException(status_code=401, detail='Unauthorized')
- return session
-
[email protected]('/api/composio/tools')
-async def handle_get(request, session = Depends(get_session)):
- try:
- tools = await composio.tools.get(session.user.id,
- toolkits=request.query_params.get('toolkits', '').split(',') if request.query_params.get('toolkits') else []
- )
- return tools
- except Exception as error:
- raise HTTPException(status_code=500, detail=str(error))
-
[email protected]('/api/composio/tools')
-async def handle_post(request, session = Depends(get_session)):
- try:
- result = await composio.tools.execute(request.json['tool_slug'],
- user_id=session.user.id, # Use session user ID
- arguments=request.json['arguments']
- )
- return result
- except Exception as error:
- raise HTTPException(status_code=500, detail=str(error))
-```
-
-```typescript TypeScript
-// pages/api/composio/tools.ts
-import { Composio } from '@composio/core';
-import { getServerSession } from 'next-auth';
-
-const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
-
-export default async function handler(req, res) {
- // Get authenticated user from NextAuth
- const session = await getServerSession(req, res);
-
- if (!session?.user) {
- return res.status(401).json({ error: 'Unauthorized' });
- }
-
- if (req.method === 'GET') {
- try {
- const tools = await composio.tools.get(session.user.id, {
- toolkits: req.query.toolkits?.split(',') || []
- });
- res.json(tools);
- } catch (error) {
- res.status(500).json({ error: error.message });
- }
- }
-
- if (req.method === 'POST') {
- try {
- const result = await composio.tools.execute(req.body.toolSlug, {
- userId: session.user.id, // Use session user ID
- arguments: req.body.arguments
- });
- res.json(result);
- } catch (error) {
- res.status(500).json({ error: error.message });
- }
- }
-}
-```
-</CodeGroup>
-
-## Common Mistakes and Solutions
-
-### Mistake 1: Using `default` in Production
-
-<CodeGroup>
-```python Python
-# ❌ Wrong - using default in production
-result = await composio.tools.execute('GMAIL_SEND_EMAIL',
- user_id='default',
- arguments={'to': '[email protected]', 'subject': 'Test'}
-)
-
-# ✅ Correct - use actual user ID
-result = await composio.tools.execute('GMAIL_SEND_EMAIL',
- user_id=request.user.id,
- arguments={'to': '[email protected]', 'subject': 'Test'}
-)
-```
-
-```typescript TypeScript
-// ❌ Wrong - using default in production
-const result = await composio.tools.execute('GMAIL_SEND_EMAIL', {
- userId: 'default',
- arguments: { to: '[email protected]', subject: 'Test' }
-});
-
-// ✅ Correct - use actual user ID
-const result = await composio.tools.execute('GMAIL_SEND_EMAIL', {
- userId: req.user.id,
- arguments: { to: '[email protected]', subject: 'Test' }
-});
-```
-</CodeGroup>
-
-### Mistake 2: Trusting Client-Provided User IDs
-
-<CodeGroup>
-```python Python
-# ❌ Wrong - trusting client data
[email protected]('/api/execute')
-async def execute():
- result = await composio.tools.execute(request.json['tool_slug'],
- user_id=request.json['user_id'], # ❌ Client could provide any user ID!
- arguments=request.json['arguments']
- )
-
-# ✅ Correct - use server-side authentication
[email protected]('/api/execute')
-@require_auth
-async def execute():
- result = await composio.tools.execute(request.json['tool_slug'],
- user_id=request.user.id, # ✅ From authenticated session
- arguments=request.json['arguments']
- )
-```
-
-```typescript TypeScript
-// ❌ Wrong - trusting client data
-app.post('/api/execute', (req, res) => {
- const result = await composio.tools.execute(req.body.toolSlug, {
- userId: req.body.userId, // ❌ Client could provide any user ID!
- arguments: req.body.arguments
- });
-});
-
-// ✅ Correct - use server-side authentication
-app.post('/api/execute', requireAuth, (req, res) => {
- const result = await composio.tools.execute(req.body.toolSlug, {
- userId: req.user.id, // ✅ From authenticated session
- arguments: req.body.arguments
- });
-});
-```
-</CodeGroup>
-
-### Mistake 3: Inconsistent User ID Format
-
-<CodeGroup>
-```python Python
-# ❌ Wrong - mixing different formats
-user_id1 = user.email # "[email protected]"
-user_id2 = user.id # "12345"
-user_id3 = user.username # "john_doe"
-
-# ✅ Correct - consistent format throughout app
-user_id = user.id # Always use the same property
-```
-
-```typescript TypeScript
-// ❌ Wrong - mixing different formats
-const userId1 = user.email; // "[email protected]"
-const userId2 = user.id; // "12345"
-const userId3 = user.username; // "john_doe"
-
-// ✅ Correct - consistent format throughout app
-const userId = user.id; // Always use the same property
-```
-</CodeGroup>
-
-## User ID Patterns Summary
-
-| Pattern | Use Case | Example | Security Level |
-|---------|----------|---------|----------------|
-| Database UUID | Production apps | `550e8400-e29b-41d4-a716-446655440000` | ✅ High |
-| Username | Simple apps | `john_doe_123` | ✅ Medium |
-| Organization ID | Enterprise | `org_acme_corp` | ✅ High |
-| Email | Not recommended | `[email protected]` | ⚠️ Medium |
-| `default` | Testing only | `default` | ❌ Low |
-
-## Key Takeaways
-
-1. **User IDs are the foundation** of Composio's security model
-2. **Use your database primary keys** for best security and consistency
-3. **Never use `default` in production** multi-user applications
-4. **Always validate user IDs** against your authentication system
-5. **Organization IDs** are perfect for enterprise/team applications
-6. **Keep user IDs server-side** and never expose them to clients
-
----
-
-**🔐 Remember**: User IDs are your security boundary. Get this right, and everything else becomes much easier and more secure.
\ No newline at end of file
diff --git a/fern/pages/src/get-started/core-concepts.mdx b/fern/pages/src/get-started/core-concepts.mdx
deleted file mode 100644
index 3f57ae208..000000000
--- a/fern/pages/src/get-started/core-concepts.mdx
+++ /dev/null
@@ -1,565 +0,0 @@
----
-title: Core Concepts
-subtitle: Overview of the core concepts of Composio
-image: 'https://og.composio.dev/api/og?title=Core%20Concepts' # image for socials
-keywords: ''
-hide-nav-links: false
----
-
-Understanding Composio's core concepts is essential for building robust applications. This guide explains the fundamental building blocks and how they work together to provide seamless integration with external services.
-
-## Essential Concepts
-
-### 1. **User IDs** - The Foundation
-
-User IDs are the cornerstone of Composio's security model. Every operation requires a User ID to ensure proper data isolation. You can use the default user ID `default` for public APIs, or create a user ID for each user in your application.
-
-<CodeGroup>
-```python Python
-# ✅ Each user has their own isolated context
-user_a_tools = await composio.tools.get('user_a', toolkits=['github'])
-user_b_tools = await composio.tools.get('user_b', toolkits=['github'])
-```
-
-```typescript TypeScript
-// ✅ Each user has their own isolated context
-const userATools = await composio.tools.get('user_a', { toolkits: ['github'] });
-const userBTools = await composio.tools.get('user_b', { toolkits: ['github'] });
-```
-</CodeGroup>
-
-**Why User IDs Matter:**
-
-- **Security**: Prevents users from accessing each other's data
-- **Isolation**: Each user's connected accounts are separate
-- **Scaling**: Supports multi-tenant applications
-- **Compliance**: Meets data privacy requirements
-
-[**→ Learn more about User IDs**](./user-ids.md)
-
----
-
-### 2. **Tools** - Individual Actions
-
-Tools are specific actions you can perform, like "Get GitHub Repository" or "Send Email". Each tool has defined inputs and outputs.
-
-<CodeGroup>
-```python Python
-# A tool execution
-result = await composio.tools.execute('GITHUB_GET_REPO',
- user_id='user_123',
- arguments={
- 'owner': 'composio',
- 'repo': 'sdk'
- }
-)
-```
-
-```typescript TypeScript
-// A tool execution
-const result = await composio.tools.execute('GITHUB_GET_REPO', {
- userId: 'user_123',
- arguments: {
- owner: 'composio',
- repo: 'sdk',
- },
-});
-```
-</CodeGroup>
-
-**Tool Properties:**
-
-- **Slug**: Unique identifier (e.g., `GITHUB_GET_REPO`)
-- **Input Parameters**: What data the tool needs
-- **Output**: What data the tool returns
-- **Authentication**: Whether the tool requires user authorization
-
----
-
-### 3. **Toolkits** - Collections of Tools
-
-Toolkits group related tools from the same service. For example, the GitHub toolkit contains tools for repositories, issues, pull requests, and more.
-
-<CodeGroup>
-```python Python
-# Get all tools from the GitHub toolkit
-github_tools = await composio.tools.get('user_123',
- toolkits=['github']
-)
-
-# Available toolkits include: gmail, slack, notion, hubspot, salesforce, etc.
-```
-
-```typescript TypeScript
-// Get all tools from GitHub toolkit
-const githubTools = await composio.tools.get('user_123', {
- toolkits: ['github'],
-});
-
-// Available toolkits include: gmail, slack, notion, hubspot, salesforce, etc.
-```
-</CodeGroup>
-
-**Popular Toolkits:**
-
-- **GitHub**: Repository management, issues, PRs
-- **Gmail**: Email sending, reading, searching
-- **Slack**: Messaging, channels, user management
-- **Google Calendar**: Event management, scheduling
-- **Notion**: Database operations, page creation
-
-[**→ Explore Tools & Toolkits**](./tools-and-toolkits.md)
-
----
-
-### 4. **Connected Accounts** - User Authorizations
-
-Connected Accounts represent a user's authorized connection to an external service. Users must authorize access before tools can act on their behalf.
-
-<CodeGroup>
-```python Python
-# User authorizes GitHub access
-connection_request = await composio.connected_accounts.initiate('user_123', 'ac_authconfig_id')
-
-# After user completes OAuth flow
-connected_account = await composio.connected_accounts.wait_for_connection(connection_request.id)
-
-# Now tools can access user's GitHub data
-repos = await composio.tools.execute('GITHUB_LIST_REPOS',
- user_id='user_123',
- connected_account_id=connected_account.id
-)
-```
-
-```typescript TypeScript
-// User authorizes GitHub access
-const connectionRequest = await composio.connectedAccounts.initiate('user_123', 'ac_authconfig_id');
-
-// After user completes OAuth flow
-const connectedAccount = await composio.connectedAccounts.waitForConnection(connectionRequest.id);
-
-// Now tools can access user's GitHub data
-const repos = await composio.tools.execute('GITHUB_LIST_REPOS', {
- userId: 'user_123',
- connectedAccountId: connectedAccount.id,
-});
-```
-</CodeGroup>
-
-**Connection Types:**
-
-- **OAuth2**: Most common (GitHub, Google, Slack)
-- **API Keys**: For services like OpenAI, Anthropic
-- **Basic Auth**: Username/password authentication
-- **Custom**: Service-specific authentication methods
-
-[**→ Learn about Connected Accounts**](./connected-accounts.md)
-
----
-
-### 5. **Auth Configs** - Authentication Templates
-
-Auth Configs define how authentication works for each toolkit. They specify the authentication method and required credentials.
-
-<CodeGroup>
-```python Python
-# Create a custom auth config for GitHub
-auth_config = await composio.auth_configs.create('github', {
- 'type': 'use_composio_managed_auth',
- 'name': 'My GitHub Integration'
-})
-```
-
-```typescript TypeScript
-// Create a custom auth config for GitHub
-const authConfig = await composio.authConfigs.create('github', {
- type: 'use_composio_managed_auth',
- name: 'My GitHub Integration',
-});
-```
-</CodeGroup>
-
-**Auth Config Types:**
-
-- **Composio Managed**: Composio handles OAuth apps and credentials
-- **User Credentials**: Users provide their own API keys/credentials
-- **Custom Auth**: Custom authentication flows
-- **No Auth**: For public APIs that don't require authentication
-
-[**→ Understanding Auth Configs**](./auth-configs.md)
-
----
-
-### 6. **Providers** - AI Platform Integration
-
-Providers adapt Composio tools for different AI platforms, handling the formatting and execution patterns each platform expects.
-
-<CodeGroup>
-```python Python
-from composio.providers.openai import OpenAIProvider
-from composio.providers.langchain import LangChainProvider
-
-# OpenAI Provider (non-agentic)
-openai_composio = Composio(
- provider=OpenAIProvider()
-)
-
-# LangChain Provider (agentic)
-langchain_composio = Composio(
- provider=LangChainProvider()
-)
-```
-
-```typescript TypeScript
-import { OpenAIProvider } from '@composio/openai';
-import { LangChainProvider } from '@composio/langchain';
-
-// OpenAI Provider (non-agentic)
-const openaiComposio = new Composio({
- provider: new OpenAIProvider(),
-});
-
-// LangChain Provider (agentic)
-const langchainComposio = new Composio({
- provider: new LangChainProvider(),
-});
-```
-</CodeGroup>
-
-**Provider Types:**
-
-- **Non-Agentic**: Format tools for external use (OpenAI, Anthropic, Google)
-- **Agentic**: Control tool execution internally (LangChain, Vercel AI)
-
-[**→ Learn about Providers**](./providers.md)
-
-## How It All Works Together
-
-Here's how these concepts work together in a typical application:
-
-### 1. **Setup Phase**
-
-<CodeGroup>
-```typescript TypeScript
-// Initialize with your preferred provider
-const composio = new Composio({
- apiKey: process.env.COMPOSIO_API_KEY,
- provider: new OpenAIProvider(),
-});
-```
-
-```python Python
-# Initialize with your preferred provider
-composio = Composio(
- api_key=os.environ.get('COMPOSIO_API_KEY'),
- provider=OpenAIProvider()
-)
-```
-</CodeGroup>
-
-### 2. **User Onboarding**
-
-<CodeGroup>
-```typescript TypeScript
-// When a user wants to connect GitHub
-const connectionRequest = await composio.connectedAccounts.initiate(
- user.id, // Your user's ID
- 'ac_123322' // Auth config ID to connect
-);
-
-// User completes OAuth flow in browser
-// Connection is established automatically
-```
-
-```python Python
-# When a user wants to connect GitHub
-connection_request = await composio.connected_accounts.initiate(
- user.id, # Your user's ID
- 'ac_123322' # Auth config ID to connect
-)
-
-# User completes OAuth flow in browser
-# Connection is established automatically
-```
-</CodeGroup>
-
-### 3. **Tool Execution**
-
-<CodeGroup>
-```typescript TypeScript
-// Execute tools on behalf of the user
-const result = await composio.tools.execute('GITHUB_CREATE_ISSUE', {
- userId: user.id,
- arguments: {
- owner: 'myorg',
- repo: 'myrepo',
- title: 'Bug Report',
- body: 'Description of the bug...',
- },
-});
-```
-
-```python Python
-# Execute tools on behalf of the user
-result = await composio.tools.execute('GITHUB_CREATE_ISSUE',
- user_id=user.id,
- arguments={
- 'owner': 'myorg',
- 'repo': 'myrepo',
- 'title': 'Bug Report',
- 'body': 'Description of the bug...'
- }
-)
-```
-</CodeGroup>
-
-### 4. **AI Integration**
-
-<CodeGroup>
-```typescript TypeScript
-// Use tools with AI models
-const tools = await composio.tools.get(user.id, {
- toolkits: ['github', 'slack'],
-});
-
-const completion = await openai.chat.completions.create({
- model: 'gpt-4',
- messages: [{ role: 'user', content: 'Create a GitHub issue and notify the team on Slack' }],
- tools: tools, // Composio tools formatted for OpenAI
-});
-```
-
-```python Python
-# Use tools with AI models
-tools = await composio.tools.get(user.id,
- toolkits=['github', 'slack']
-)
-
-completion = await openai.chat.completions.create(
- model='gpt-4',
- messages=[{'role': 'user', 'content': 'Create a GitHub issue and notify the team on Slack'}],
- tools=tools # Composio tools formatted for OpenAI
-)
-```
-</CodeGroup>
-
-## Key Patterns and Best Practices
-
-### 1. **User-Centric Design**
-
-<CodeGroup>
-```typescript TypeScript
-// ✅ Always scope operations to specific users
-const userTools = await composio.tools.get(userId, { toolkits: ['github'] });
-
-// ❌ Don't use 'default' in production
-const defaultTools = await composio.tools.get('default', { toolkits: ['github'] });
-```
-
-```python Python
-# ✅ Always scope operations to specific users
-user_tools = await composio.tools.get(user_id, toolkits=['github'])
-
-# ❌ Don't use 'default' in production
-default_tools = await composio.tools.get('default', toolkits=['github'])
-```
-</CodeGroup>
-
-### 2. **Error Handling**
-
-<CodeGroup>
-```typescript TypeScript
-try {
- const result = await composio.tools.execute('GITHUB_GET_REPO', {
- userId: user.id,
- arguments: { owner: 'composio', repo: 'sdk' },
- });
-
- if (result.successful) {
- // Handle success
- } else {
- // Handle tool-level errors
- console.error('Tool error:', result.error);
- }
-} catch (error) {
- // Handle SDK-level errors
- console.error('SDK error:', error.message);
-}
-```
-
-```python Python
-try:
- result = await composio.tools.execute('GITHUB_GET_REPO',
- user_id=user.id,
- arguments={'owner': 'composio', 'repo': 'sdk'}
- )
-
- if result.successful:
- # Handle success
- pass
- else:
- # Handle tool-level errors
- print('Tool error:', result.error)
-except Exception as error:
- # Handle SDK-level errors
- print('SDK error:', str(error))
-```
-</CodeGroup>
-
-### 3. **Connection Management**
-
-<CodeGroup>
-```typescript TypeScript
-// Check if user has required connections
-const accounts = await composio.connectedAccounts.list({
- userIds: [userId],
- toolkitSlugs: ['github'],
-});
-
-if (accounts.items.length === 0) {
- // Prompt user to connect GitHub
- const connection = await composio.toolkits.authorize(userId, 'github');
- // Redirect to connection.redirectUrl
-}
-```
-
-```python Python
-# Check if user has required connections
-accounts = await composio.connected_accounts.list(
- user_ids=[user_id],
- toolkit_slugs=['github']
-)
-
-if len(accounts.items) == 0:
- # Prompt user to connect GitHub
- connection = await composio.toolkits.authorize(user_id, 'github')
- # Redirect to connection.redirect_url
-```
-</CodeGroup>
-
-## Advanced Concepts
-
-### Custom Tools
-
-Create your own tools for services not yet supported:
-
-<CodeGroup>
-```typescript TypeScript
-const customTool = await composio.tools.createCustomTool({
- slug: 'MY_CUSTOM_TOOL',
- name: 'My Custom Tool',
- description: 'Does something specific',
- inputParameters: z.object({
- // Define the input parameters for the tool
- param1: z.string().describe('The first parameter'),
- param2: z.string().describe('The second parameter'),
- }),
- execute: async params => {
- // Your custom logic
- return { data: {}, successful: true, error: null };
- },
-});
-```
-
-```python Python
-custom_tool = await composio.tools.create_custom_tool(
- slug='MY_CUSTOM_TOOL',
- name='My Custom Tool',
- description='Does something specific',
- input_parameters=z.object({
- # Define the input parameters for the tool
- 'param1': z.string().describe('The first parameter'),
- 'param2': z.string().describe('The second parameter')
- }),
- execute=lambda params: {
- # Your custom logic
- 'data': {},
- 'successful': True,
- 'error': None
- }
-)
-```
-</CodeGroup>
-
-### MCP (Model Control Protocol)
-
-Expose tools to AI models through a standardized protocol:
-
-<CodeGroup>
-```typescript TypeScript
-const mcpServer = await composio.mcp.create('my-server', [
- {
- toolkit: 'github',
- authConfigId: 'auth_123',
- allowedTools: ['GITHUB_GET_REPO', 'GITHUB_CREATE_ISSUE'],
- },
-]);
-```
-
-```python Python
-mcp_server = await composio.mcp.create('my-server', [
- {
- 'toolkit': 'github',
- 'auth_config_id': 'auth_123',
- 'allowed_tools': ['GITHUB_GET_REPO', 'GITHUB_CREATE_ISSUE']
- }
-])
-```
-</CodeGroup>
-
-### Triggers
-
-React to real-time events from external services:
-
-<CodeGroup>
-```typescript TypeScript
-composio.triggers.subscribe(
- event => {
- console.log('New email received:', event.payload);
- },
- {
- toolkits: ['gmail'],
- triggerSlug: ['GMAIL_NEW_EMAIL'],
- }
-);
-```
-
-```python Python
-def handle_event(event):
- print('New email received:', event.payload)
-
-composio.triggers.subscribe(
- handle_event,
- toolkits=['gmail'],
- trigger_slug=['GMAIL_NEW_EMAIL']
-)
-```
-</CodeGroup>
-
-## Quick Reference
-
-| Concept | Purpose | Example |
-| --------------------- | ------------------- | ------------------- |
-| **User ID** | Identity & security | `'user_123'` |
-| **Tool** | Specific action | `'GITHUB_GET_REPO'` |
-| **Toolkit** | Service collection | `'github'` |
-| **Connected Account** | User authorization | OAuth to GitHub |
-| **Auth Config** | Auth template | GitHub OAuth app |
-| **Provider** | AI integration | OpenAI, LangChain |
-
-## Common Questions
-
-**Q: Can one user have multiple connected accounts for the same service?**
-A: Yes, but it requires explicitly allowing multiple connections when creating them.
-
-**Q: Do I need to store authentication tokens?**
-A: No, Composio manages all tokens securely. You only work with Connected Account IDs.
-
-**Q: Can I use tools without user authentication?**
-A: Some tools (like HackerNews) don't require authentication, but most do.
-
-**Q: How do I know which tools require authentication?**
-A: Tools that require authentication will throw an error if no connected account is provided.
-
-
-**💡 Remember**: These concepts work together to provide a secure, scalable, and flexible way to integrate external services into your applications. Start with the basics and gradually explore advanced features as your needs grow.
diff --git a/fern/pages/src/dev-setup.mdx b/fern/pages/src/get-started/dev-setup.mdx
similarity index 100%
rename from fern/pages/src/dev-setup.mdx
rename to fern/pages/src/get-started/dev-setup.mdx
diff --git a/fern/pages/src/core-concepts/providers.mdx b/fern/pages/src/get-started/providers.mdx
similarity index 100%
rename from fern/pages/src/core-concepts/providers.mdx
rename to fern/pages/src/get-started/providers.mdx