What is a shared connection, and when should you share one?

A shared connection is an app account, connected through CoreSpeed, that every member of the organization and every agent principal can act through. The alternative is a private connection, usable only by the member who connected it and that member's clients. Any member can connect either kind. Private is what you get unless you choose shared.

What is the difference between private and shared?

Every connection on CoreSpeed is one or the other. A connection is the stored credential for one app account plus the namespaced tools it exposes, such as slack__post_message or notion__create_page. The agent receives tools, never the token; CoreSpeed stores the credential, refreshes it when the provider allows, and keeps it inside the organization boundary.

Visibility decides whose tools/list the connection's tools appear in. A private connection appears for the member who connected it, in every client that member signs into. A shared connection appears for every member of the org and for every agent principal.

Who can connect, and who can remove?

Any member can connect either kind, from Dashboard → Connectors, by OAuth, by pasting an API key, or through the organization's own OAuth app where an admin has registered one. The choice between private and shared is made at connect time.

Removal follows the same shape. A private account is removed by its member. A shared one is removed by whoever connected it or by an org admin. The authenticated index reports both rules per account as can_remove, so a client never has to guess:

curl https://api.corespeed.io/connectors \
  -H "Authorization: Bearer $CORESPEED_API_KEY"

One connector can hold several accounts, two Slack workspaces or a personal and a company X handle. Each has an alias, renamable with manage__accounts_rename, and tools take an optional account argument to pick one. With several in scope and none named, the call answers ambiguous_account with the aliases to choose from.

What is an organization integration?

Some vendors let CoreSpeed's app be installed as an actor of its own. Slack can install a workspace bot. Linear can install the app, which works under the alias corespeed-bot. On those connectors, org-wide access is the organization integration rather than a shared member account. Only an org admin connects one, and what is done through it is attributed to the app, never to whoever connected it. A member's own account on those connectors is private only.

The difference shows in the app. A message posted through a member account appears as that member. A message posted through the workspace bot appears as the bot. For an agent acting on behalf of the team, the bot is usually the honest actor.

Why do agent principals reach shared only?

An agent principal is the org's third kind of principal, with an identity of its own and an sk-csa- key. Any member can create one and becomes its owner, the member who answers for it. Ownership is accountability and nothing more: the agent inherits neither the owner's connections nor the owner's role.

So an agent key never reaches a member's private connections. It reaches the shared ones and the organization integrations. If an unattended job you run needs Slack, the Slack connection has to be shared or the workspace bot has to be installed. A member key (sk-cs-) acts as the member who created it and has that member's full reach, private included, which is why unattended jobs should hold an agent key instead. The authentication page describes the principals.

How are actions attributed?

Dashboard → Activity records action, actor, organization and outcome. A call through a shared connection is attributed to the member or key that made it, and API-key activity goes through the key's owning identity. A call through an organization integration is attributed to the app. Members see their own actions; org admins see the org. The activity page has the record shape.

Smart Approval judges writes through shared connections like any other. A policy sentence such as "Ask me before anything goes to a public channel" applies whether the Slack account is private, shared, or the bot.

When should you share a connection?

Share an account that belongs to the company and that several people or agents act through: the team Slack workspace, the engineering Linear workspace, the company X handle, the shared Notion workspace. Keep private an account that is yours: your Gmail, your Google Drive, your personal X handle. The test is whether a teammate's agent posting as that account would be right.

Two more reasons to share. An agent principal cannot reach anything private, so any connection an unattended job needs must be shared. And a shared connection has one credential to refresh and one to reauthorize: when it goes needs_reauth, one person reconnects in Dashboard → Connectors and every caller recovers. The connectors page covers the three ways to connect.

FAQ

Is a connection shared by default? No. Every connection is private unless you choose shared when connecting.

Can an agent key use my private Gmail? No. Agent principals reach shared connections only. A member key acting as you can.

Who can remove a shared connection? Whoever connected it, or an org admin. The index says so per account as can_remove.

Can I share my Slack account on a connector that has a workspace bot? On connectors with an organization integration, a member's own account is private only. Org-wide access goes through the bot an admin installs.

Does sharing change what the agent holds? No. The agent receives tools in either case. The token stays in CoreSpeed's custody.