Skip to content
bucker

Connections

A connection links your organization to an outside provider so Bucker can read what the provider holds. The first provider is PostHog's feature flags, read-only. A connection is the answer to two questions an agent otherwise has to guess: what may Bucker do through this link, and how fresh is what it read.

What a connection holds

Part Meaning
Provider and kind Who it points at (posthog) and what it is (flag_vendor).
Status proposed until a key has been verified, then active; disabled stops every use; revoked.
Purposes A connection can hold up to three credentials: read (pull state), signal (receive pushed facts) and apply (change the provider). Each has its own key and its own scopes. Only read is used today; no adapter changes anything at a provider.
Scopes The labels a key is limited to, for example feature_flag:read. Widening one (for example to activity_log:read) is a person's act.
Capabilities pull, webhook, change_request_status, apply.
Coverage Per signal: ok, lagging, unknown or missing, with a short reason (credential_rejected, breaker_open, connection_disabled, expired, ...). Silence from a push path reads unknown, never ok.
Write grant Whether the key was verified read-only: none, present (the key is refused) or not_verifiable (the provider did not say).
Egress addresses The addresses this deployment publishes so you can allow-list them at the provider. Empty when none are published.

Connecting a provider

Every step is a person's, in their own signed-in session. No agent, token or MCP client can start a connection, enter a key, widen a scope, disable or delete.

  1. In Settings > Connections, choose the provider and create a connect link. An organization owner or admin can do this.
  2. The link is shown once and works once, for 24 hours. Only its hash is stored.
  3. Create a personal API key at the provider with read access only. Enter it in the form on the same page (or at the link). Bucker asks the provider what the key may do, refuses a key that can write or that lacks read access, then seals it.
  4. The key is never shown again, and no route, tool, audit row or notification carries it. To change it, connect again: the old key is kept sealed for 24 hours and then destroyed.

A link alone sets nothing: using it needs a signed-in owner or admin of the organization it belongs to. Another organization's link, an expired link and a used link all answer the same "not found".

Who can do what

Act Needs
See the list Owner, admin or viewer (governance:read)
Start a connection, enter a key, widen scopes Owner or admin (egress:admin)
Disable or delete Owner (org admin)

Disabling stops every use at once; every signal reads missing with the reason connection_disabled and the sealed key stays. Deleting destroys the sealed key and removes the flags mirrored through it. Revoking the key at the provider is yours to do.

Reading connections from an agent: connections_list

connections_list returns the same inventory over MCP, with no credential material: provider, kind, status, project (if narrowed), scopes per purpose, capabilities, coverage per signal, whether the key was verified read-only, freshness, the egress addresses and the last provider incident. It is read-only and takes optional provider, status and limit filters. A connection narrowed to one project is listed only to a caller who can read that project: a viewer who reaches some projects through their teams sees the organization-wide connections and those of their own projects, and is not told the others exist.

It is held. It asks governance:read, a scope the MCP ceiling does not carry until the OAuth security review (SG-059) is signed off, so no token a production path can mint is able to list or call it yet. It sits in the platform toolset.

Provider-supplied names (scope names, signal names, coverage reasons and the project slug) are customer- or provider-written text. They are scrubbed, scanned for instructions and capped before they are returned, and are listed in trust.untrustedFields with their classes. Treat them as data. An empty answer says why in evidence.emptyReason (not_ingested: nothing is connected; filtered_out: nothing matches the filter).

What Bucker will never do through a connection

An adapter works from a manifest of the exact requests it may make. For PostHog that is four read requests: list flags, get a flag, read the flag activity log and probe the key. It does not call write, person, recording, raw-event, query, cohort or key-management endpoints, and it does not follow a link the provider returns. Every call passes the organization's egress allow-list, is rate-limited and has its response scanned for credential-shaped text.