Skip to main content

​
Connections

The console and /v0/capabilities expose only operator-configured apps. Browser sessions are a separate provider capability; see Browsers. The app catalog is searchable and paginated; it can hold all provider toolkits without fitting their configuration IDs into a Worker environment variable. Connections require an organization key; inbox/project-scoped keys cannot manage a shared workspace account. Read, create/reconnect and disconnect use api_key_read, api_key_create and api_key_delete permissions respectively.

​
Operator setup

Apply the API migrations, including 0020_product_records.sql, and bind D1. Configure these API Worker values through the normal deployment secret/variable path: Create the corresponding Composio auth configs, including the OAuth application’s required permissions and provider setup. Lupin’s catalog reads this allowlist; arbitrary app names cannot start authorization. Auth-config IDs are server-side configuration and are not returned by capabilities. For the complete toolkit inventory, apply 0024_provider_catalog.sql and use the operator provisioner infra/provision-composio-catalog.mjs. It paginates provider toolkits/auth configs, reuses enabled configs, creates managed OAuth blueprints where supported, and tries empty app credentials for non-OAuth schemes. User API keys and login credentials are collected later by Composio’s hosted connect flow; they are never invented or stored in Lupin’s catalog. Custom OAuth apps that require client credentials remain explicitly unavailable. No-auth toolkits are labeled separately because they do not require an account connection. The provisioner requires explicit LUPIN_COMPOSIO_PROVISION=1 for writes and a LUPIN_COMPOSIO_CATALOG_PATH output path. Its adjacent checkpoint is written before each creation. Preserve that checkpoint when resuming an interrupted run; uncertain creations are recovered from inventory, never blindly repeated. The activation workflow validates the safe catalog metadata and stores it in D1; only the Composio project API key becomes a Worker secret. Existing small COMPOSIO_AUTH_CONFIGS maps remain a fallback for slugs absent from D1, while explicit disabled D1 entries take precedence. GET /v0/connections/catalog?search=github&limit=50 searches configured apps. Use include_unavailable=true to inspect no-auth and setup-required entries, and pass next_cursor as cursor to fetch another page. Public catalog responses include app names/status only, never auth-config IDs or customer accounts. Capabilities include only the first 100 configured apps plus total/next-cursor metadata; clients should use the catalog endpoint to search the complete list.

​
Connect and inspect

The backend uses Composio’s v3.1 hosted link API, with workspace organization ID as user_id. The provider owns OAuth credentials; Lupin stores account IDs in D1 and returns a sanitized account/status/scopes view. The return URL is navigation only. Query parameters such as status=ACTIVE cannot activate a connection. Each list checks the saved account’s provider-reported user_id and status before displaying it. Reconnect keeps the old account registered while replacement authorization is pending. After the provider confirms the replacement is active, a subsequent list retires the old account. Finish the pending authorization or disconnect before starting a second reconnect. Disconnect validates ownership, performs upstream revocation for authorized accounts, then deletes the provider account and durable registry. If revocation fails or the toolkit cannot revoke programmatically, Lupin preserves the record and reports failure so an operator can reconcile access. Already revoked accounts and absent accounts support retry cleanup. Creation and reconnect require a preserved Idempotency-Key. The console keeps the attempt identity across retries and page reloads. A durable journal records the provider outcome before publishing the local connection; recovery replays only local persistence. HTTP 409 reconciliation_required includes an operation ID when the outcome is uncertain. Keep the same key and contact support before starting another attempt. Reconnect’s resource lock remains held through the durable replacement, so concurrent deletion cannot remove an unfinished account.

​
Discover and execute app tools

After authorization is active, discover the app’s available tools and their real input schemas with GET /v0/connections/:connection_id/tools?search=issues or:
Only tools belonging to the connection’s configured toolkit can execute. The API verifies the durable connection, provider account ownership and active status, then pins the discovered tool version and account revision. Reconnecting or switching the account invalidates old approvals. The provider’s v3.1 tool execution API receives only the server-derived organization/account IDs and approved tool arguments. Custom auth parameters, credential overrides and arbitrary proxy requests are not accepted. Discovery uses api_key_read; execution uses api_key_create, both with an organization key. The consumer agent requires an exact human approval for every app tool execution, including apparent reads, because toolkit operations can have side effects. MCP clients receive write annotations and must obtain authorization themselves. The durable operation journal prevents concurrent execution and retry duplication. Provider timeouts retain an uncertain operation and its usage reservation; contact support before issuing a different operation key. App execution is treated as an unbounded paid effect and is blocked when a matching spending limit is active.

​
Recovery

connections_not_configured means the provider/D1/catalog setup is incomplete. unsupported_app means the app is outside the enabled catalog. A provider error never proves successful authorization or disconnect; retry after checking provider status. Persistent lifecycle operations use a durable compare-and-set to reject concurrent changes. If a Worker terminates while holding an operation marker, an operator must reconcile the recorded account(s) in Composio before clearing the marker in D1; do not delete the registry merely to hide an error. If provider cleanup and durable storage both fail during link creation, inspect the Composio project for the unfinished account before retrying. The local test suite mocks provider responses; a sandbox OAuth walkthrough is required before activation.