A managed connector is a connection whose OAuth credentials, token refresh, and upstream API calls are held by Composio instead of your deployment. Where a vendor MCP server or a direct API connection keeps that account’s own secret in Chickpea, a managed connector keeps only an opaque account reference and the non-secret policy. This page covers opting in with one project key, connecting an account to an Agent, the deployment-owned alternative, rotation and reconnects, and the limits that reach an admin.
Chickpea keeps the parts that decide authority: team or personal ownership, the capability ceiling for each account and Agent, write confirmation, and schedule state. Composio owns the credentials and the execution.
What the managed lane covers
Thirteen connectors use this lane. Every other connector in the catalog stays on its own vendor MCP server or direct API lane and needs no Composio project.
| Connector | Access | What you select after sign-in |
|---|---|---|
| Gmail | Read and write | Nothing beyond the account |
| Google Calendar | Read and write | Nothing beyond the account |
| Google Drive | Read and write | Nothing beyond the account |
| Google Sheets | Read and write | Nothing beyond the account |
| Google Docs | Read and write | Nothing beyond the account |
| Google Slides | Read and write | Nothing beyond the account |
| Notion | Read and write | Pages and databases, in Notion’s own picker |
| Google Search Console | Read | One or more sites |
| Google Analytics | Read | One or more GA4 properties |
| HubSpot | Read and write | One portal, validated on connect |
| Gong | Read | One or more workspaces |
| Google Ads | Read and write | One or more client accounts |
| YouTube | Read and write | One or more channels |
Chickpea requests the write lane when that lane is ready for the connector and the read lane otherwise. Each Google service is a separate connection and a separate consent screen.
Prerequisites
- The Owner or Admin role in Chickpea. Saving, replacing, or disabling the key requires the
admin.configurepermission, which Owners and Admins hold. A Member who picks a managed connector is told to ask an Owner or Admin. - A Composio project for this installation. Use separate projects for development, staging, and production, and one project per Chickpea installation. Projects isolate keys, connected accounts, auth configurations, and webhooks.
- A project key. In Composio, open Settings → Project Settings → API Keys and create one.
- Composio project settings. In Project Settings → General, leave OAuth user verification set to Not configured, because Chickpea supplies its own callback URL for every sign-in. Set execution log storage to Don’t store data before sending customer data.
Opt in with one project key
Open the Connectors settings
In Admin, open Settings → Connectors. The Managed connectors section shows the project status and one row per managed connector.
Paste the project key
Enter it in Composio project key and select Validate and save. Chickpea validates the key against Composio, stores it in the encrypted credential store, and never shows it again.
Let Chickpea prepare the connectors
Chickpea creates or reuses one deterministic managed auth configuration per toolkit in that project. You never copy an auth configuration ID.
Read the connector rows
Each row ends in Ready, Setup required, or Blocked by deployment policy. If some rows still need setup, select Retry setup; ready connectors stay usable while others fail.
You can also start this from an Agent. Picking a managed connector on the Connections tab with no key configured opens a Set up dialog; Save key and continue stores the key and then continues to the sign-in you started.
Connect an account to an Agent
A connection belongs permanently to one Agent. The same person can authorize the same external identity for a second Agent, but that creates a separate Chickpea connection and a separate Composio account.
Open the Agent's Connections tab
Save the Agent first. The hosted sign-in is issued for one saved Agent, one connector, and one owner kind.
Pick the connector and the owner
Choose Personal so each person signs in with their own account, or Team for one shared account. Team accounts require the Owner or Admin role.
Finish sign-in in the new tab
Chickpea opens Composio’s hosted sign-in in a second tab and waits in the first. Use Open sign-in if your browser blocked the tab, Check again after an error, or Cancel to revoke an uncommitted request. The attempt lasts 30 minutes, and refreshing the Chickpea tab restores the waiting state.
Select the resources, where the connector asks for them
Search Console, Analytics, Gong, Google Ads, and YouTube stay pending until you choose. Select Choose, tick the sites, properties, workspaces, client accounts, or channels, then select Save access. Manager accounts are never offered for Google Ads.
Review the permissions on the provider’s sign-in screen. The upstream grant can be broader than the capabilities Chickpea exposes to the Agent, and a read-only connection does not narrow what you approved there.
Verify
The connection row carries no warning state and shows the account and its owner. A row that still reads Setup required is pending, usually waiting for its resource selection, Needs attention means the account must reconnect, and Disconnected means it is revoked. In Slack, ask the Agent for one read: a Gmail profile, a Gong workspace list, or a Search Console site.
Use a deployment-owned project key
Set these when the deployment, not Admin, owns the configuration. Settings → Connectors then reports the key as Configured by deployment and never displays, replaces, or disables it.
| Variable | When | Purpose |
|---|---|---|
COMPOSIO_API_KEY |
Deployment-owned setup | The project key, set as a secret |
CHICKPEA_COMPOSIO_CONFIGURATION_MODE |
Deployment-owned setup | Set to deployment to make Admin read-only |
COMPOSIO_WEBHOOK_SECRET |
Optional | Verifies Composio’s expiry webhook |
COMPOSIO_GOOGLE_ADS_ACCESS_LEVEL |
Google Ads, optional | explorer, basic, or standard |
COMPOSIO_GOOGLE_ADS_PERMISSIBLE_USE |
Google Ads with basic or standard |
reporting for reads, ad_management for writes |
COMPOSIO_YOUTUBE_GENERAL_DAILY_QUOTA_UNITS |
YouTube | Daily general-unit budget, default 10000 |
COMPOSIO_YOUTUBE_SEARCH_DAILY_CALL_LIMIT |
YouTube | Daily search calls, default 100 |
COMPOSIO_YOUTUBE_UPLOAD_DAILY_CALL_LIMIT |
YouTube | Daily uploads, default 100 |
COMPOSIO_YOUTUBE_QUOTA_AUDIT_APPROVED |
YouTube, only above the defaults | Set to true after the quota audit |
After enabling this mode, open Settings → Connectors and select Prepare connector defaults once. Existing connected accounts keep executing until preparation finishes, but new authorizations are unavailable.
Leave both Google Ads variables unset on the ordinary managed path. explorer enables both lanes. basic and standard also need a permissible use, where reporting enables reads only and ad_management enables writes. test is not usable in production, and an unknown or half-declared pair shows the connector as Blocked by deployment policy. These values are operator assertions, so check the tier in the Google Ads API Center first.
Rotate or replace the project key
- Rotating
COMPOSIO_API_KEY. Chickpea sees the fingerprint change, raises the provider generation, and pauses managed execution until an Owner or Admin retries preparation. That retry inspects every preserved account with the new key, restores the matching ones, and marks accounts from another project for reconnection. - Replacing a stored key in Admin. Select Replace project key, paste the new one, and confirm. The dialog counts the connected accounts and schedules the change affects. A key from a different project leaves preserved accounts needing a reconnect.
- Disabling in Chickpea. Disable in Chickpea pauses managed execution and dependent schedules while keeping Agent bindings and the remote Composio accounts. A Runs as member resumes each affected schedule after connections recover.
Compatibility overrides for installations that already own explicit auth configurations are named COMPOSIO_<lane>_AUTH_CONFIG_ID in .env.example. Run preparation again after changing one. An override that is not enabled, Composio-managed, and unrestricted disables only its own lane.
Reconnect an account
Select Reconnect on the connection row. The Chickpea connection ID and its Agent binding survive, so the Agent keeps its skills, instructions, and other connections. Schedules that an expiry paused stay in needs_attention until someone reviews and resumes them. Reconnecting is also how you change a Notion page selection, because Notion’s own picker is the authorization boundary.
Add the expiry webhook
The webhook is optional and only surfaces upstream revocation sooner. Without it, Chickpea polls while connecting, revalidates the exact account on every execution, and moves an account to reconnection after a definitive authorization failure.
Register the endpoint in Composio
Point the subscription at https://<chickpea-host>/webhooks/composio.
Store the subscription secret
Set COMPOSIO_WEBHOOK_SECRET to the value Composio returns. The endpoint answers 503 with not_configured until that secret exists, verifies the raw-body signature, and accepts only the account-expiry event.
Limits
| Limit | Value | Scope |
|---|---|---|
| Gong date ranges | 90 days | Calls, coaching, interaction, and scorecard reads |
| Gong transcripts | 100 segments and 100,000 characters per result | Each transcript read |
| Analytics and Search Console ranges | 366 days | Every report |
| Google Ads reports | 366 days and 500 rows | Every report family |
| HubSpot page size | 100 records | Object search |
| YouTube daily quota | 10,000 general units, 100 searches, 100 uploads | The whole deployment, per Pacific-time day |
| YouTube upload | 8 MB, MP4, WebM, or QuickTime | One file per upload |
Some limits are shapes rather than numbers. Gong is read-only, and several of its company settings endpoints ignore the workspace you selected, so treat user, interaction, scorecard, and call-outcome reads as company-visible. Google Ads creates every campaign, ad group, keyword, and ad paused, and a budget confirmation shows the account, currency, and amount. Composio’s default YouTube app can share quota between its users, so an upstream quota error is possible while your local budget still has headroom. HubSpot shows an unverified-app warning during sign-in, and its triggers stay off.
Disconnect an account
Open the connection row menu and select Disconnect account. Keep the project key in place until every managed account is gone: without it Chickpea cannot delete the remote account, so it refuses the local-only disconnect, returns a restore-credentials error, and leaves the connection in Needs attention with its schedules paused.
Next steps
- Agents: the other parts of an Agent, including connections on the other lanes.
- A tour of Admin: where Settings, Agents, and the audit views live.
- Authority and confirmation: how credentials, authority, and confirmation work across every lane.
- Configure your deployment: setting secrets and variables on Cloudflare and on Node.