Manage third-party integrations for a Butterbase app (e.g., Gmail, Slack, Google Calendar).
Actions:
- "configure": Enable or manage a third-party integration toolkit for an app
- "rotate_credentials": Swap in new BYO OAuth client_id/client_secret without dropping connected accounts
- "disable": Disable a configured integration toolkit
- "list_available": List available integrations that can be enabled (curated or full catalog)
- "list_connected": List connected integration accounts for an app
- "list_tools": List available tool actions for connected integrations
- "execute_action": Execute a tool action on a connected integration (e.g., send email, create event)
Parameters by action:
configure: { app_id, action: "configure", toolkit, scopes?, display_name?, oauth_credentials? }
rotate_credentials: { app_id, action: "rotate_credentials", toolkit, oauth_credentials }
disable: { app_id, action: "disable", toolkit }
list_available: { app_id, action: "list_available", search? }
list_connected: { app_id, action: "list_connected" }
list_tools: { app_id, action: "list_tools", toolkit? }
execute_action: { app_id, action: "execute_action", tool_name, params?, user_id? }
Curated toolkits (first-class support, no BYO credentials needed):
gmail, google-calendar, slack, google-sheets, notion, github, hubspot, outlook, google-drive, discord
Non-curated toolkits (Twitter, LinkedIn, Reddit, etc.) usually require BYO OAuth credentials.
Use list_available with search=<name> first to inspect requires_byo_credentials and auth_schemes.
Example — configure (curated, managed auth):
Input: { app_id: "app_abc123", action: "configure", toolkit: "gmail", scopes: ["gmail.send"] }
Output: { id: "...", toolkit_slug: "gmail", enabled: true }
Example — configure (BYO OAuth credentials, e.g. Twitter/X):
Input: {
app_id: "app_abc123", action: "configure", toolkit: "twitter",
scopes: ["tweet.read", "tweet.write", "users.read", "offline.access"],
oauth_credentials: { client_id: "...", client_secret: "...", auth_scheme: "OAUTH2" }
}
Output: { id: "...", toolkit_slug: "twitter", enabled: true }
Example — rotate_credentials (after upstream OAuth client rotation):
Input: {
app_id: "app_abc123", action: "rotate_credentials", toolkit: "twitter",
oauth_credentials: { client_id: "new...", client_secret: "new..." }
}
Output: { id: "...", toolkit_slug: "twitter", enabled: true }
Example — list_available:
Input: { app_id: "app_abc123", action: "list_available", search: "twitter" }
Output: { integrations: [{ toolkit: "twitter", displayName: "Twitter", curated: false, auth_schemes: ["OAUTH2"], requires_byo_credentials: true }, ...] }
Example — list_connected:
Input: { app_id: "app_abc123", action: "list_connected" }
Output: { connections: [{ toolkit_slug: "gmail", status: "active", connected_at: "..." }, ...] }
Example — list_tools:
Input: { app_id: "app_abc123", action: "list_tools", toolkit: "gmail" }
Output: { tools: [{ name: "GMAIL_SEND_EMAIL", description: "Send an email", parameters: {...} }, ...] }
Example — execute_action (send email):
Input: { app_id: "app_abc123", action: "execute_action", tool_name: "GMAIL_SEND_EMAIL", params: { to: "user@example.com", subject: "Hello", body: "World" } }
Output: { successful: true, data: { messageId: "..." } }
Common errors:
- INTEGRATIONS_NOT_CONFIGURED: Integration API key not set
- INTEGRATIONS_BYO_CREDENTIALS_REQUIRED: Toolkit has no Composio-managed auth; pass oauth_credentials
- INTEGRATIONS_UPSTREAM_ERROR: Composio rejected the auth config (bad slug or bad credentials)
- INTEGRATIONS_NOT_CONNECTED: User hasn't connected this integration
- INTEGRATIONS_EXECUTION_FAILED: Integration tool execution failed
- RESOURCE_NOT_FOUND: App doesn't exist