Connections

A connection's secret material is encrypted at rest. Visibility governs something different: who can see that a connection exists and reuse it. Settings → Connections is the organization-wide end of that model — the connections every workspace can reach — and the visibility control on each individual connection is what decides which connections get there.

The page requires the ADMIN authority, and both it and the visibility model are Enterprise Edition.

Organization Connections

The page is headed Organization Connections, described as "Manage organization-wide shared connections.", with an Environment selector and a New Connection button.

Column	Description
Name	The connection's name.
Component	The component it authenticates, with its icon. A connection can outlive the component that defined it, in which case the raw component name is shown.
Environment	The environment the connection belongs to.
Created By	Who created it.
Last Modified	When it last changed.

Creating one opens the standard connection dialog, so an organization connection gets the same component picker, the component's real connection properties, and the same OAuth2 flow as any other connection. Organization connections are deleted rather than demoted — this scope is terminal.

The visibility model

Every connection carries exactly one visibility, ordered PRIVATE < WORKSPACE < ORGANIZATION:

Visibility	Who can reach it	Typical use
PRIVATE	The owner, plus anyone named in a grant.	A personal sandbox credential.
WORKSPACE	Every member of the owning workspace.	A shared infrastructure credential used across a workspace's projects.
ORGANIZATION	Every member of every workspace in the organization.	A corp-wide credential.

Every connection is created WORKSPACE-visible — shared with its workspace unless its owner withholds it. That is the default for every resource type, not a special case for connections.

The picker on the connection dialog offers three states:

Shared with workspace — WORKSPACE. Not gated on admin: it is the default, so gating it would fail every ordinary create.
Private — PRIVATE, withheld from the workspace.
Specific people — also stored as PRIVATE, distinguished only by the presence of grant rows naming individual users.

"Specific people" is deliberately not a fourth stored value. Keeping one stored state machine means the server never has to reconcile a value that would be indistinguishable from PRIVATE the moment its last grant was revoked. Moving away from Specific people leaves the grants in place rather than deleting them, so demoting again restores the same audience.

ORGANIZATION is not offered in that picker — it is reached through the Organization Connections page above. Asking for it at creation time is rejected with "Only PRIVATE or WORKSPACE visibility can be set on connection creation".

Grants live in a polymorphic resource_grant table keyed by resource type, resource id, and user id, with a unique constraint across the three; granting the same user twice is a no-op rather than an error.

Per-edition behavior

Community Edition — every connection is force-written WORKSPACE. There is no picker and no grants, because CE has no authorization boundary between workspace members.
Embedded — every connection is force-written PRIVATE. An embedded connection belongs to a connected end user of your product, not to a workspace member, so workspace reach would be wrong in a way that crosses customers.

Both overrides are applied in the facade, ignoring the request body, so a hand-crafted request cannot bypass them.

WORKSPACE grants use plus existence, not read plus write. Both connection REST controllers obfuscate authorizationParameters and return parameters as null, and no connection API mutates authorization parameters after creation. A colleague can run a workflow against your account; they cannot extract the credential or repoint it somewhere else.

Visibility is also a precondition of the permission check, not a filter running beside it — without that, a member holding CONNECTION_EDIT would pass a by-id check for a connection the list correctly hides.

Changing visibility

Every connection in the automation Connections list carries a scope badge next to its name, showing where the connection currently reaches:

Badge	Icon	Meaning
Private	lock	"Visible only to you. Share it to give named colleagues access."
Specific people	people	"Withheld from the workspace and shared with named colleagues."
Workspace	building	"Visible to every member of the current workspace."
Organization	globe	"Visible to every member across all workspaces in the organization."

The badge is a button. Click it and the visibility picker opens beneath, with the same three choices as the creation dialog.

To share a connection with the whole workspace, click the badge and choose Shared with workspace.

To share a connection with named colleagues, click the badge, choose Specific people, and add them from the workspace-member list that appears. Removing someone from that list revokes their access. The badge then reads Specific people with the number of people named.

To withhold a connection, choose Private. Any people you had named keep their grants, so switching back restores the same audience rather than starting from an empty list.

Changes apply as you make them — there is no separate save step. Adding or removing people is applied as a difference against the current list rather than as a wholesale replacement, so the platform never revokes and re-adds every grant on each edit.

Where the feature is unavailable — Community Edition, or any surface with no workspace context — no badge appears at all. There is no read-only fallback: a connection simply shows its name, and visibility is not part of the UI. A badge that renders without opening a picker means something else: the feature is on, but the connection has no id yet, as with one that has not been saved.

At the API level

The picker is backed by four operations, all owner-or-admin:

Operation	Effect
`setConnectionVisibility(workspaceId, connectionId, visibility)`	Sets a connection's reach. Rejects `ORGANIZATION` (set through `createOrganizationConnection` instead) and refuses to narrow to `PRIVATE` while an active deployment uses the connection.
`grantConnectionAccess(workspaceId, connectionId, userId)`	Names one user on a `PRIVATE` connection. Idempotent.
`revokeConnectionAccess(workspaceId, connectionId, userId)`	Removes that user's grant.
`connectionGrants(workspaceId, connectionId)`	Lists who a connection was handed to.

There is deliberately no set-grants operation — expressing the picker's list as one would mean revoking every grant and re-adding it on each keystroke.

A grantee must already be a member of the owning workspace, and a rejection reuses the unknown-connection error so user ids cannot be enumerated through it. connectionGrants is owner-or-admin for the same reason: a plain viewer must not learn who else holds access.

Grants are deleted with the connection.

What gets audited

Event	When
`CONNECTION_CREATED`	A connection was created.
`CONNECTION_DELETED`	A connection was deleted.
`CONNECTION_VISIBILITY_CHANGED`	A connection's reach changed.
`CONNECTION_ACCESS_GRANTED`	A user was named on a private connection.
`CONNECTION_ACCESS_REVOKED`	A user's grant was removed.
`CONNECTION_REASSIGNED`	A connection's owner changed.

Every one of these except CONNECTION_CREATED and CONNECTION_ACCESS_GRANTED is strict-audit: if the entry cannot be written, the operation fails rather than proceeding unrecorded. Those are exactly the events that can remove someone's access. See Audit Events.

Metrics

bytechef_connection_create (counter) increments on every connection created through the workspace facade, tagged visibility=PRIVATE|WORKSPACE, so you can watch how much credential sharing actually happens against how much stays private. The tag reads the persisted visibility rather than the request body, so it reflects the CE and embedded overrides. Organization connections are created through their own facade and are not counted here.

Failed audit writes on non-strict events are counted on bytechef_connection_audit_failed.

On this page