Connections

A connection is one external account an Agent may use: the support team’s Zendesk, your work Gmail, a remote MCP server. Where a channel grant decides where an Agent may speak and a skill teaches it a procedure, a connection decides which account it may act in. This page covers team and personal accounts, the lanes a credential arrives by, how one is chosen on a turn, and what disconnecting removes.

Team accounts and personal accounts

Every connection belongs to one Agent for its lifetime. A team account is shared authority the Agent’s editors manage, like the support team’s Zendesk. A personal account belongs to one member inside one Agent, like your work Gmail, and runtime use requires both that Agent’s connection and your identity. Authorizing the same external account for a second Agent creates a separate connection with its own consent.

Each Agent’s accounts are listed on its Connections tab in Admin. A connection is two records: the account, which holds the provider, the label, the policy, and a reference to the secret, and the Agent’s binding, which says the Agent may use it and how far. Every account carries one of four lifecycle values.

The lanes a credential arrives by

Chickpea ships 35 connector presets. A connector is the preset, the kind of service; a connection is one authorized account of that kind.

An MCP preset carries a server URL and an auth kind of none, oauth, bearer, or a named header. An API preset carries hosts, path prefixes, a header name, and the methods that account may use. Native MCP and native API take the same fields, unfilled.

Opting into the managed lane is the one exception to keeping credentials with you. Chickpea still owns account selection, capability limits, confirmation policy, and which provider account is used on every call.

How one connection is chosen on a turn

An account is eligible only when its binding on this Agent is enabled, its lifecycle is ready, and, for a personal account, the member taking the turn owns it. Someone else’s personal Gmail is not in the room.

From the eligible set, Chickpea picks per provider:

• One eligible account. It is used.
• Several, and the request names one. The label, the purpose, the account name, or the workspace name appears as a phrase in the request. Exactly one match wins.
• Several, and the request names none or more than one. Every account for that service is withheld and the Agent is told to ask which label to use. Its instruction is explicit: “Do not guess, invoke a withheld account, or claim the connected service is unavailable.”

Withholding covers the whole service group, so a broad Google account cannot slip in through a neighboring group while Gmail is ambiguous.

When a member has no personal account yet for a provider the Agent offers, the Agent can start one from the thread:

@revops pull my last five threads with Acme from my inbox

The Agent calls one tool, authorize_personal_connection, and posts back an authorization link. The task stops until Chickpea resumes it, and the mailbox stays closed to the Agent until the link is followed.

How the credential reaches the call

Credentials never enter model context or the tool arguments the model writes. The model picks a connection by ID and the secret goes in at egress.

• The check runs at the moment of use, not when the turn was planned. Before returning secret material the runtime re-reads the account and the binding, and confirms the member is still active and still resolves to that Slack identity.
• The binding is a ceiling, never a floor. It narrows what the account policy allows: the MCP tools, the HTTP methods, the OAuth scopes, or the managed capabilities and resources. Reauthorizing an account with wider access does not widen the Agent.
• The secret goes into the request, not into the plan. It becomes a header on that connection’s own network scope as the request leaves.
• Nothing is cached. Credentials resolve per use, and a value set as an environment variable wins over the stored one.

The egress allowlist and the network guard

Outbound access has its own policy, set in Settings → Outbound access: Allowlist permits only the hosts listed there, Open permits the whole internet, Off disables outbound access. The default is Allowlist with no hosts. It governs the sandbox’s own network; connected services are separate and keep working. Each connection gets a network scope holding only that connection’s hosts and methods, so a redirect off one of those hosts cannot reach another host or carry a write method to it. Hosts you list stay at GET and HEAD, and even Open mode adds only POST. Private and internal addresses are always blocked, and on Cloudflare every hostname resolves fresh through DNS over HTTPS on each request. A request outside its scope fails with URL blocked by connection policy: and the URL; a method outside it fails with HTTP method '<method>' not allowed. and the allowed list.

Nothing said in the conversation changes any of this. Authority comes from stored grants and saved instructions, read from stored state and re-checked at the moment of each use, never from anything produced during the turn.

What an Agent may do with an account

Minor reversible writes may proceed without confirmation. Consequential ones (sending a message or email, deleting, publishing, broad or bulk changes) require confirmation unless the saved Agent instructions explicitly authorize that class of action.

Interrupted authorization

An OAuth flow that leaves Slack for a browser is tracked as a continuation, bound to the workspace, the member, the Agent, the channel and thread, the task, the provider, and the account. It carries a capability the provider’s callback has to present back, lasts 15 minutes, and can be authorized once: a replayed callback is refused. When the callback lands, and only if that member is still active, Chickpea resumes the exact Slack task it left. One that could not resume straight away waits in a durable index a periodic repair pass drains.

Disconnecting

Disconnecting is not a delete. In order, Chickpea pauses the schedules that depend on the account, revokes it at the managed provider when there is one, removes the stored secret, marks the account revoked, and retires it from those schedules. The account row stays, so history still reads.

Dependent schedules stop rather than run without the account, because every run rechecks the whole chain and a missing connection raises connection_unavailable. The deployment keeps no way back in: a new connection is a new authorization.

Disconnecting requires the right to edit the Agent, plus either the Owner or Admin role, or ownership of the personal account being disconnected.

On Node

Connections, selection, injection, and the network guard behave the same on Node. Node runs no scheduler, so the pause step has nothing live to stop.

Why it works this way

Binding an account to one Agent keeps the reach of a published Agent equal to what that Agent alone was given, with no shared pool of credentials to leak across. Re-reading the binding at the moment of use means a change you make lands on the next call, not at the end of the conversation.

Selection fails closed for a related reason. Two Gmail accounts on one Agent are two different mailboxes, and a wrong guess is not undone by an apology in the thread.

What is not covered

• Connections are not shared between Agents. The same external account authorized twice is two connections with two consents.
• A connection is not a channel grant. It says what an Agent may reach, never where it may speak.
• Composio-managed accounts are the exception to self-hosted state. Their OAuth storage, refresh, and execution live at Composio.
• Disconnecting a native connection is not revoking at the provider. Chickpea drops its copy; tokens you issued elsewhere are yours to retire.

Next steps

• Agents: the rest of this section, including connecting a service and managed connectors.
• How Chickpea works: where connections sit in one turn, from mention to reply.
• Security model: the guarantees above with the mechanism behind each.
• A tour of Admin: the browser app where accounts and outbound access are managed.