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.

Add example usage of user_id in the docs

haxziecb46a71b1e54
diff --git a/README.md b/README.md
index 579b60193..ab586d4c4 100644
--- a/README.md
+++ b/README.md
@@ -248,6 +248,9 @@ composio/
# Create a new provider
pnpm create:provider <provider-name> [--agentic]
+ # Create a new example
+ pnpm create:example <example-name>
+
# Check peer dependencies
pnpm check:peer-deps
@@ -255,6 +258,29 @@ composio/
pnpm update:peer-deps
```
+## Creating a New Example
+
+1. Use the create:example script:
+
+ ```bash
+ pnpm create:example my-example
+ ```
+
+2. The script will create a new example in `examples/my-example` with:
+
+ - `package.json` with minimal dependencies (`@composio/core` and `dotenv`)
+ - `tsconfig.json` for TypeScript configuration
+ - `.env.example` and `.env` files for environment variables
+ - `src/index.ts` with basic Composio SDK setup
+ - `README.md` with setup and usage instructions
+ - Dependencies automatically installed
+
+3. Next steps after creation:
+ - Edit `.env` and add your `COMPOSIO_API_KEY`
+ - Customize `src/index.ts` with your example logic
+ - Add any additional dependencies as needed
+ - Run with `pnpm start` or `pnpm dev` (with file watching)
+
## Creating a New Provider
1. Use the create:provider script:
diff --git a/docs/core-concepts.md b/docs/core-concepts.md
index fa3147ee7..32ae19206 100644
--- a/docs/core-concepts.md
+++ b/docs/core-concepts.md
@@ -2,6 +2,128 @@
Composio SDK is built around a set of key concepts that work together to provide a seamless integration experience for third-party services and tools.
+## User IDs
+
+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.
+
+### ⚠️ Critical Security Considerations
+
+User IDs are crucial for security and data isolation. You must be extremely careful when handling user IDs to ensure:
+
+- Users can only access their own connected accounts
+- Tool executions are performed in the correct user context
+- No unauthorized access to other users' data
+
+### 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
+
+```typescript
+// ❌ Don't use 'default' in production for multi-user apps
+const tools = await composio.tools.get('default', {
+ toolkits: ['github'],
+});
+
+// ❌ This could expose other users' data
+const result = await composio.tools.execute('GITHUB_GET_REPO', {
+ userId: 'default',
+ arguments: { owner: 'example', repo: 'repo' },
+});
+```
+
+### Production User IDs
+
+In production applications with multiple users, always use unique identifiers for each user. The best practices are:
+
+#### ✅ **Recommended: Database UUID**
+
+```typescript
+// Use your database's user ID (UUID, primary key, etc.)
+const userId = user.id; // e.g., "550e8400-e29b-41d4-a716-446655440000"
+
+const tools = await composio.tools.get(userId, {
+ toolkits: ['github'],
+});
+
+const result = await composio.tools.execute('GITHUB_GET_REPO', {
+ userId: userId,
+ arguments: { owner: 'example', repo: 'repo' },
+});
+```
+
+#### ✅ **Acceptable: Unique Username/Identifier**
+
+```typescript
+// Use a unique, stable identifier from your system
+const userId = user.username; // e.g., "john_doe_123"
+// or
+const userId = user.externalId; // e.g., "auth0|507f1f77bcf86cd799439011"
+```
+
+#### ⚠️ **Not Recommended: Email Address**
+
+```typescript
+// While functional, emails can change and may cause issues
+const userId = user.email; // e.g., "[email protected]"
+```
+
+### Example: Multi-User Application Flow
+
+```typescript
+import { Composio } from '@composio/core';
+
+const composio = new Composio({
+ apiKey: process.env.COMPOSIO_API_KEY,
+});
+
+// 1. User initiates GitHub connection
+async function connectUserToGitHub(userId: string) {
+ const connectionRequest = await composio.toolkits.authorize(userId, 'github');
+ return connectionRequest.redirectUrl;
+}
+
+// 2. Get user's connected GitHub tools
+async function getUserGitHubTools(userId: string) {
+ return await composio.tools.get(userId, {
+ toolkits: ['github'],
+ });
+}
+
+// 3. Execute tool for specific user
+async function getUserRepos(userId: string) {
+ return await composio.tools.execute('GITHUB_LIST_REPOS', {
+ userId: userId,
+ arguments: {
+ per_page: 10,
+ },
+ });
+}
+
+// Usage in your API endpoint
+app.get('/api/github/repos', async (req, res) => {
+ const userId = req.user.id; // Get from your auth system
+
+ try {
+ const repos = await getUserRepos(userId);
+ res.json(repos.data);
+ } catch (error) {
+ res.status(500).json({ error: 'Failed to fetch repos' });
+ }
+});
+```
+
+### Best Practices
+
+1. **Always validate user IDs** before passing them to Composio methods
+2. **Use your authentication system** to ensure users can only access their own data
+3. **Keep user IDs consistent** across your application and Composio
+4. **Never expose user IDs** in client-side code or logs
+5. **Use meaningful, stable identifiers** that won't change over time
+
## Tools
Tools are the fundamental units of functionality in Composio. Each tool represents a specific action that can be performed, such as "Get GitHub Repository" or "Send Email". Tools have:
@@ -94,19 +216,19 @@ const customTool = await composio.tools.createCustomTool({
param1: {
type: 'string',
description: 'First parameter',
- required: true
- }
+ required: true,
+ },
},
outputParameters: {
result: {
type: 'string',
- description: 'The result of the operation'
- }
+ description: 'The result of the operation',
+ },
},
handler: async (params, context) => {
// Custom logic here
return { data: { result: 'Success!' } };
- }
+ },
});
```
@@ -119,4 +241,4 @@ Triggers allow your application to respond to events from external services. The
const triggers = await composio.triggers.get({
toolkits: ['github'],
});
-```
\ No newline at end of file
+```
diff --git a/examples/triggers/src/index.ts b/examples/triggers/src/index.ts
index b5fb7b96f..3fb5e031d 100644
--- a/examples/triggers/src/index.ts
+++ b/examples/triggers/src/index.ts
@@ -29,7 +29,7 @@ async function main() {
// Get available tools
const tools = await composio.tools.get('default', {
// Specify the apps you want to use
- // apps: ['gmail', 'googlecalendar'],
+ toolkits: ['gmail', 'googlecalendar'],
limit: 10,
});