Composio Integration - Zarna Documentation

Overview

Composio provides unified OAuth flows and API access for Gmail, Outlook, Google Drive, Calendar, and 100+ other applications. Website: composio.dev

What is Composio?

Composio simplifies third-party integrations by providing:

Unified OAuth: Single flow for multiple providers
Token Management: Automatic token refresh
API Abstraction: Consistent API across different services
Webhook Handling: Real-time notifications
Security: Enterprise-grade security and compliance

Services Integrated

Gmail

Email OAuth, sending, reading, searching

Outlook

Microsoft email OAuth and operations

Google Drive

File sync and storage

Google Calendar

Event management and scheduling

Setup

1. Create Composio Account

Go to composio.dev
Sign up for an account
Create a new project

2. Get API Key

From Composio Dashboard → Settings → API Keys:

# Add to .env
COMPOSIO_API_KEY=your-composio-api-key

3. Configure OAuth Apps

For each service (Gmail, Outlook, Drive, Calendar):

Go to Composio Dashboard → Integrations
Select integration (e.g., Gmail)
Create Auth Config
Set callback URL: http://localhost:8000/email_bot/gmail/oauth/callback
Copy Auth Config ID:

COMPOSIO_GMAIL_AUTH_CONFIG_ID=your-config-id
COMPOSIO_OUTLOOK_AUTH_CONFIG_ID=your-config-id
COMPOSIO_DRIVE_AUTH_CONFIG_ID=your-config-id
COMPOSIO_CALENDAR_AUTH_CONFIG_ID=your-config-id

OAuth Flow with Composio

Initialization

from composio import Composio

composio = Composio(api_key=os.getenv("COMPOSIO_API_KEY"))

# Build auth URL
auth_url = composio.get_auth_url(
    entity_id=user_id,  # Your user ID
    auth_config_id=os.getenv("COMPOSIO_GMAIL_AUTH_CONFIG_ID"),
    redirect_url="http://localhost:8000/oauth/callback"
)

# Redirect user to auth_url
return {"auth_url": auth_url}

Callback Handling

@app.get("/oauth/callback")
async def oauth_callback(
    connected_account_id: str,
    status: str,
    state: str
):
    """
    Handle OAuth callback from Composio
    """
    if status != "success":
        return {"error": "OAuth failed"}

    # Get connected account details
    account = composio.get_connected_account(connected_account_id)

    # Store in database
    supabase.table("oauth_tokens").insert({
        "user_id": user_id,
        "provider": "google",
        "composio_account_id": connected_account_id,
        "email": account.email
    }).execute()

    return {"success": True}

Using Composio Tools

Gmail

from composio import ComposioToolSet

toolset = ComposioToolSet(api_key=composio_api_key)

# Get profile
profile = toolset.execute_action(
    action="GMAIL_GET_PROFILE",
    entity_id=user_id
)

# Send email
result = toolset.execute_action(
    action="GMAIL_SEND_EMAIL",
    entity_id=user_id,
    params={
        "to": "recipient@example.com",
        "subject": "Hello",
        "body": "Email content"
    }
)

# Search emails
emails = toolset.execute_action(
    action="GMAIL_SEARCH_EMAILS",
    entity_id=user_id,
    params={
        "query": "from:sender@example.com",
        "max_results": 10
    }
)

Outlook

# Get profile
profile = toolset.execute_action(
    action="OUTLOOK_OUTLOOK_GET_PROFILE",
    entity_id=user_id
)

# Send email
result = toolset.execute_action(
    action="OUTLOOK_SEND_EMAIL",
    entity_id=user_id,
    params={
        "to": "recipient@example.com",
        "subject": "Hello",
        "body": "Email content"
    }
)

Google Drive

# List files
files = toolset.execute_action(
    action="GOOGLEDRIVE_LIST_FILES",
    entity_id=user_id,
    params={
        "page_size": 100,
        "query": "name contains 'report'"
    }
)

# Download file
content = toolset.execute_action(
    action="GOOGLEDRIVE_DOWNLOAD_FILE",
    entity_id=user_id,
    params={
        "file_id": "file-id-here"
    }
)

# Upload file
upload = toolset.execute_action(
    action="GOOGLEDRIVE_UPLOAD_FILE",
    entity_id=user_id,
    params={
        "name": "document.pdf",
        "content": file_content,
        "mime_type": "application/pdf"
    }
)

Google Calendar

# List events
events = toolset.execute_action(
    action="GOOGLECALENDAR_LIST_EVENTS",
    entity_id=user_id,
    params={
        "time_min": "2024-01-01T00:00:00Z",
        "time_max": "2024-12-31T23:59:59Z",
        "max_results": 100
    }
)

# Create event
event = toolset.execute_action(
    action="GOOGLECALENDAR_CREATE_EVENT",
    entity_id=user_id,
    params={
        "summary": "Meeting with Acme Corp",
        "start": "2024-01-22T14:00:00Z",
        "end": "2024-01-22T15:00:00Z",
        "attendees": ["contact@acme.com"]
    }
)

Entity Management

What is an Entity?

An entity in Composio represents a user in your system:

entity_id: Your user’s UUID
Connected Accounts: OAuth accounts connected by this entity
Isolation: Each entity’s tokens are separate

Create Entity

composio.create_entity(entity_id=user_id)

Get Entity

entity = composio.get_entity(entity_id=user_id)
print(f"Connected accounts: {entity.connected_accounts}")

Security

Token Storage

Composio handles token storage securely:

Tokens never exposed to you
Automatic token refresh
Encrypted at rest
Compliance certifications

Best Practices

Use entity-based isolation

Always pass user_id as entity_id to ensure proper isolation

Store only account IDs

Store connected_account_id, not raw OAuth tokens

Handle webhook signatures

Verify webhook signatures to prevent spoofing

Implement error handling

OAuth can fail - handle errors gracefully

Environment Variables

# Composio API
COMPOSIO_API_KEY=your-composio-api-key

# OAuth Auth Config IDs
COMPOSIO_GMAIL_AUTH_CONFIG_ID=your-gmail-config
COMPOSIO_OUTLOOK_AUTH_CONFIG_ID=your-outlook-config
COMPOSIO_DRIVE_AUTH_CONFIG_ID=your-drive-config
COMPOSIO_CALENDAR_AUTH_CONFIG_ID=your-calendar-config

# Callback URL base
API_BASE_URL=http://localhost:8000

Webhooks

Set Up Webhooks

# Register webhook
composio.create_webhook(
    url="https://api.zarna.com/webhooks/composio",
    events=["account.connected", "account.disconnected", "token.refreshed"]
)

Handle Webhooks

@app.post("/webhooks/composio")
async def handle_composio_webhook(request: Request):
    """
    Handle Composio webhooks
    """
    payload = await request.json()
    signature = request.headers.get("X-Composio-Signature")

    # Verify signature
    if not composio.verify_webhook(payload, signature):
        raise HTTPException(status_code=401, detail="Invalid signature")

    # Handle events
    if payload["event"] == "account.connected":
        # User connected new account
        account_id = payload["connected_account_id"]
        # Update database

    elif payload["event"] == "token.refreshed":
        # Token was refreshed
        pass

    return {"status": "received"}

Available Actions

Gmail Actions

GMAIL_GET_PROFILE - Get user profile
GMAIL_SEND_EMAIL - Send email
GMAIL_SEARCH_EMAILS - Search emails
GMAIL_GET_EMAIL - Get specific email
GMAIL_CREATE_DRAFT - Create draft
GMAIL_DELETE_EMAIL - Delete email

Outlook Actions

OUTLOOK_OUTLOOK_GET_PROFILE - Get user profile
OUTLOOK_SEND_EMAIL - Send email
OUTLOOK_LIST_EMAILS - List emails
OUTLOOK_GET_EMAIL - Get specific email

Drive Actions

GOOGLEDRIVE_LIST_FILES - List files
GOOGLEDRIVE_DOWNLOAD_FILE - Download file
GOOGLEDRIVE_UPLOAD_FILE - Upload file
GOOGLEDRIVE_DELETE_FILE - Delete file
GOOGLEDRIVE_SHARE_FILE - Share file

Calendar Actions

GOOGLECALENDAR_LIST_EVENTS - List events
GOOGLECALENDAR_CREATE_EVENT - Create event
GOOGLECALENDAR_UPDATE_EVENT - Update event
GOOGLECALENDAR_DELETE_EVENT - Delete event

Troubleshooting

OAuth callback not working

Solution:

Verify callback URL matches exactly in Composio dashboard
Check API_BASE_URL is set correctly
Ensure backend is accessible from internet (use ngrok for local dev)

Token refresh failing

Solution:

Check Composio API key is valid
Verify OAuth scopes include offline_access
Check account hasn’t been revoked by user

Action execution failing

Solution:

Verify entity_id exists and has connected account
Check action parameters are correct
Review Composio logs in dashboard

Next Steps

OAuth Setup Guide

Complete OAuth implementation guide

Gmail Integration

Email bot API

Drive Integration

Google Drive setup

Calendar Integration

Calendar integration

Authentication

Cloud Storage

Productivity

Database

​Overview

​What is Composio?

​Services Integrated

Gmail

Outlook

Google Drive

Google Calendar

​Setup

​1. Create Composio Account

​2. Get API Key

​3. Configure OAuth Apps

​OAuth Flow with Composio

​Initialization

​Callback Handling

​Using Composio Tools

​Gmail

​Outlook

​Google Drive

​Google Calendar

​Entity Management

​What is an Entity?

​Create Entity

​Get Entity

​Security

​Token Storage

​Best Practices

​Environment Variables

​Webhooks

​Set Up Webhooks

​Handle Webhooks

​Available Actions

​Gmail Actions

​Outlook Actions

​Drive Actions

​Calendar Actions

​Troubleshooting

​Next Steps

OAuth Setup Guide

Gmail Integration

Drive Integration

Calendar Integration

​Resources

Overview

What is Composio?

Services Integrated

Setup

1. Create Composio Account

2. Get API Key

3. Configure OAuth Apps

OAuth Flow with Composio

Initialization

Callback Handling

Using Composio Tools

Gmail

Outlook

Google Drive

Google Calendar

Entity Management

What is an Entity?

Create Entity

Get Entity

Security

Token Storage

Best Practices

Environment Variables

Webhooks

Set Up Webhooks

Handle Webhooks

Available Actions

Gmail Actions

Outlook Actions

Drive Actions

Calendar Actions

Troubleshooting

Next Steps

Resources