Guides›Composio Onboarding

Composio Onboarding

This guide covers the end-to-end workflow for enabling Composio toolkits in a project, inheriting defaults on agent create, applying per-agent overrides, and linking provider accounts.

Glossary

Project defaults: Project-scoped Composio provider settings (enabled toolkits + default enabled/disabled tools).
Snapshot: An immutable agent-specific effective config captured at create time (and on subsequent overrides).
Override: A per-agent mutation that creates a new snapshot revision; does not change project defaults.
Linked account: A per-agent, per-provider connection state (pending/active/expired/etc) used to execute tools.
- linked_user_id indicates which user initiated the most recent link for that agent/provider (console only).
Execution principal: Who tool calls should run as for a given agent.
- service: The agent's default "service account" for a business (link once, shared across conversations).
- end_user: A per-end-user identity (each end user links their own account).

0) Store Composio API Key (Enter Once)

Store the Composio API key once at the project level using the provider-keys endpoint:

Endpoint: POST /v1/projects/:id/provider-keys
List: GET /v1/projects/:id/provider-keys

bash

curl -X POST "$ROOAAK_API_URL/v1/projects/$PROJECT_ID/provider-keys" \
  -H "Authorization: Bearer $ROOAAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "composio",
    "key": "cmp_xxx"
  }'

Notes:

Keys are stored encrypted at rest; API responses return metadata only (ex: keyLast4).
Legacy composio_{provider} provider keys are still supported for backwards compatibility, but deprecated.

1) Create Project Defaults (Enable Toolkits + Tools)

Use the public API to configure Composio toolkits at project scope:

Endpoint: POST /v1/projects/:id/composio/providers
List: GET /v1/projects/:id/composio/providers

Example (enable Gmail toolkit with a minimal allowlist):

bash

curl -X POST "$ROOAAK_API_URL/v1/projects/$PROJECT_ID/composio/providers" \
  -H "Authorization: Bearer $ROOAAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gmail",
    "isEnabled": true,
    "defaultEnabledTools": ["gmail.send_email", "gmail.reply_email"],
    "defaultDisabledTools": []
  }'

Notes:

You do not need to create your own OAuth app for Gmail/Slack/etc. As soon as a provider is enabled, Rooaak will auto-provision a Composio-managed authConfigId (using your stored Composio API key) and persist it into project settings.
You may supply authConfigId explicitly, but most developers should rely on Composio-managed configs.

2) Create An Agent That Inherits Defaults

When you create an agent without a composio payload, Rooaak inherits project defaults.

bash

curl -X POST "$ROOAAK_API_URL/v1/agents" \
  -H "Authorization: Bearer $ROOAAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inbox Assistant"
  }'

3) Override Toolkits Or Tools At Agent Scope

Overrides create a new immutable snapshot revision for the agent. They do not change project defaults.

Override during create (public API)

bash

curl -X POST "$ROOAAK_API_URL/v1/agents" \
  -H "Authorization: Bearer $ROOAAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inbox Assistant (Gmail only)",
    "composio": {
      "enabledToolkits": ["gmail"],
      "disabledTools": ["gmail.delete_email"]
    }
  }'

Override after create (console API)

The console uses a session-authenticated endpoint to apply agent overrides:

PATCH /api/console/projects/:projectId/agents/:agentId/composio

This is exposed in the Console UI on the agent page under the Composio tab.

4) Link Provider Accounts (Service vs End User)

Toolkits require a linked account before tools can execute. Linking is per-agent, per-provider.

4.1 Console linking (service principal)

The Console UI links the agent's service principal (one linked account shared across conversations):

Open the agent page, go to Composio, and click Connect.
The callback is session-authenticated and bound to the agent user.

4.2 Public V1 linking (service or end_user principal)

Use these endpoints if you need per-end-user linking or if you want to drive linking from your own UI.

Initiate: POST /v1/agents/:id/composio/linked-accounts/:provider/initiate
List: GET /v1/agents/:id/composio/linked-accounts
Unlink: DELETE /v1/agents/:id/composio/linked-accounts/:provider
Callback (Composio -> Rooaak): GET /v1/agents/:id/composio/linked-accounts/:provider/callback (no auth; validated by signed state)

Initiate examples:

bash

# Link a shared business account (service principal)
curl -X POST "$ROOAAK_API_URL/v1/agents/$AGENT_ID/composio/linked-accounts/gmail/initiate" \
  -H "Authorization: Bearer $ROOAAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": { "type": "service" },
    "returnUrl": "https://yourapp.example.com/composio/complete"
  }'

bash

# Link a per-end-user account (end_user principal)
curl -X POST "$ROOAAK_API_URL/v1/agents/$AGENT_ID/composio/linked-accounts/gmail/initiate" \
  -H "Authorization: Bearer $ROOAAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": { "type": "end_user", "endUserId": "user_123" },
    "returnUrl": "https://yourapp.example.com/composio/complete"
  }'

Notes:

endUserId is developer-defined and opaque; it must match ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$.
returnUrl is optional. If provided, Rooaak will redirect to it after callback, appending provider, status, and ok=1 when active.
returnUrl is validated to prevent open redirects. The host must match Rooaak's request host, or be included in ROOAAK_PUBLIC_HOST_ALLOWLIST.
Initiate returns linkId and redirectUrl (plus url as a temporary alias for backward compatibility).

Common actionable failures:

SETUP_INCOMPLETE: Provider is not enabled at project scope, or the project is missing Composio credentials.
INVALID_CREDENTIALS: The stored Composio key does not validate the provider authConfigId.
UPSTREAM_ERROR: Composio backend rejected the request or is unavailable.

Inheritance Boundaries (What Changes What)

Changing project defaults affects new agents, but does not mutate existing agent snapshots.
Applying an override affects only that agent and creates a new snapshot revision.
Linking a linked account affects execution ability for that agent; it does not change snapshots.