Skip to content

Control Center Connect reference

Control Center Connect runs provider sign-ins for servers that have not registered their own apps. A server either uses Control Center’s hosted Connect, a Connect its organization runs (Run a Connect server), or none. The choice lives in Settings → Server → Single sign-on → Control Center Connect, cc_server connect, or CC_CONNECT_URL. A workspace follows it unless an admin picks something else for that workspace under Settings → Workspace → Integrations (Per-workspace choice).

Each provider is a lane. Under Use my own apps (or before anyone chooses), a lane runs on the server’s own app when one is fully configured, else it is unavailable. With Control Center’s or a custom Connect, Connect runs every lane it serves: the server’s own apps stay saved but are not used, for sign-ins, server automation or the status the server reports. A workspace that picked its own choice runs every lane by that choice instead.

Lane Own app needs Through Connect
github App id, private key, client id and client secret People sign in to the shared GitHub App
google Client id and client secret People connect Google Calendar
linear Client id People sign in to Linear
linear_app Client id A workspace admin connects Linear’s app actor
slack A workspace’s own Slack app connection A workspace admin connects Slack to the shared Slack app
klipy KLIPY_APP_KEY GIF search, proxied by Connect

An own app that is only partly configured makes its lane an error, never a silent fall back to Connect. A workspace on Use my own apps never goes through the server’s apps or any Connect, for any provider. Changing the server’s Connect choice signs nobody out of a workspace that made its own choice.

Connect sees Connect never sees
The server’s install id and request signatures Source code, repository contents, diffs or pull request text
The provider account that signed in, during the sign-in Tickets, transcripts or anything in a workspace database
Which workspace a credential belongs to, as an opaque id inside the seal The server’s own app secrets: they never leave the server
The repository a one-repository GitHub token is minted for Refresh tokens at rest: they exist only inside seals the server keeps
The Slack team bound to the server Linear secrets: the server exchanges Linear’s code itself
GIF search terms, when it proxies Klipy Passwords, pairing keys or model provider keys
Slack event references (team, channel, message id) and slash-command text Slack message text: Connect drops it on arrival and the server reads the message from Slack itself

Connect keeps staged sign-ins, nonces and caches for at most 10 minutes, and hourly usage counters for at most two hours. A one-repository GitHub token minted as a person stays recorded, sealed to the sign-in that asked for it, until it expires (at most 8 hours), so Connect can hand it out again and revoke it on disconnect. Its only lasting records are Slack bindings (which server each Slack team is bound to) and retired install ids. Errors carry a code, never the provider’s response. Logs record install ids only as keyed hashes, and a GitHub token only as the hashed_token GitHub’s organization audit log shows for it, so an organization owner can match the two.

Mode Setting Behavior
Unset Fresh server No lane uses Connect. Onboarding asks the server owner to choose
hosted Use Control Center’s apps https://connect.usectrl.dev, with an offline-signed configuration. The server’s own apps are not used
custom Use a custom Connect server A Connect at an HTTPS URL (http on loopback only), trusted on first use. The server’s own apps are not used
off Use my own apps No lane uses Connect. Only own apps sign people in

CC_CONNECT_URL in the server’s environment or .env locks the choice: hosted, off, or a Connect URL. Settings then shows the lock and cannot change it.

This build compiles in no hosted configuration key, so hosted mode reports hosted_unprovisioned and serves no lane. Own apps and a custom Connect work.

The hosted Connect runs as a single container. Its seal key and the shared GitHub App’s private key are environment variables there, not keys in a vault that only signs or decrypts, as GitHub recommends for an App’s private key. That is a known gap of the current setup.

A server reads Connect’s configuration at most every 10 minutes and waits at most 5 seconds for each call. When Connect is unreachable, the last good configuration stays in use and Settings marks it stale.

Settings → Workspace → Integrations → Control Center Connect overrides the server’s choice for one workspace. Every member sees it and where each sign-in runs; only a workspace admin changes it.

Choice Behavior
Same as this server The default. The workspace runs on whatever the server owner chose; the option names it
Use Control Center’s apps Control Center’s hosted Connect, whatever the server uses
Use my own apps Only the workspace’s own apps: its GitHub App, Google client, Linear application, Klipy key and Slack app. A provider without one is off here; a partial one is a setup error
Use a custom Connect server A Connect at an HTTPS address the workspace names. Addresses on a private or local network are refused
  • Any choice other than Same as this server keeps each person’s GitHub and Linear sign-ins in a slot of the workspace’s own, so they never mix with the server-wide ones
  • Switching asks first: everyone in the workspace signs in to GitHub, Linear and Google Calendar again through the new apps
  • A workspace’s own Slack app connection works under every choice; Add Control Center to Slack follows the choice
  • CC_CONNECT_URL also locks workspaces out of a Connect of their own: they can follow the server or use their own apps
  • A workspace’s custom Connect is trusted on first use for that workspace only: Trust new apps there never changes what the server or another workspace trusts
Item What it is
Install key A 32-byte seed in the server’s secrets file (connect_install_key), separate from device pairing keys
Per-Connect key An Ed25519 key derived from the seed and the Connect’s address. Every request to Connect is signed with it (RFC 9421)
Install id 26 characters derived from that public key. Shown in Settings and by cc_server connect status

The same server has a different install id for every Connect address. The id changes only when the key is rotated.

A sign-in through Connect returns a credential seal: an encrypted blob that only the Connect that made it can open. It is bound to the provider, the Connect address, the install id, the workspace, the provider account, the app and the secret generation.

  • The server stores the seal and the install id it was sealed for. Access tokens stay in memory
  • To refresh, the server sends the seal back and receives a new access token and a new seal
  • A seal whose install id or Connect address no longer matches is deleted when it is next read, and that person signs in again. This happens after a key rotation, a switch to another Connect, or a data directory restored onto a different server
  • A seal Connect cannot open is refused with access_denied

An installation of the shared GitHub App is usable from every server. Connect keeps no record of which server may use it.

  • Install GitHub App in Settings → Workspace → Integrations opens the app’s install page on GitHub. The server builds the link from the app name in Connect’s configuration
  • A one-repository token needs the app installed on the repository’s owner and the signed-in person’s access to the repository. It is that person’s own token, clamped to their role, never more
  • An organization limits Control Center on GitHub: by removing the installation, narrowing its repositories, or removing the person
  • For calls only the person can make, such as listing their installations, Connect hands the server the person’s own App user token, not a one-repository token. Signing in on a server is trusting that server with that token
  • An organization that enforces a GitHub IP allow list cannot use the hosted Connect, whose addresses are not fixed. It registers its own GitHub App instead, on its servers or on a Connect it runs
  • Disconnect revokes only that sign-in: Connect spends its refresh token once and deletes what that returns, deletes its user token and the one-repository tokens Connect minted for it. A copy of its seal kept anywhere stops working. The person’s sign-ins on other servers and workspaces keep working. To remove Control Center from a GitHub account entirely, revoke it in GitHub under Settings → Applications → Authorized GitHub Apps → Revoke

Tokens minted as the App’s bot (as: app) show the same bot on GitHub for every server that uses the same Connect: GitHub cannot tell those servers apart.

  • Every server may have the bot read and comment: read, review and comment (comments, labels, assignees and reactions on issues and pull requests)
  • Reviewing a pull request as the bot (bot, which writes pull requests) is allowed only for servers the Connect operator lists in CONNECT_GITHUB_REVIEW_BOT_INSTALLS. Every other server is answered needs_requester and publishes the review on the accountable person’s own token, which GitHub clamps to that person: the review appears under their name. This covers AI review publishing, review comments and reviewer requests
  • Pushing, creating a branch and opening a pull request (write) are never minted as the shared bot. They always use the requester’s own sign-in
  • Approving a pull request is never automated, on any token
  • A server or workspace with its own GitHub App keeps the bot for all of this, reviews included

What organization owners and members should know

Section titled “What organization owners and members should know”
  • A server someone signs in on holds their App user token: up to 8 hours per token, renewed until they disconnect. It can act as them on every repository the shared App is installed on that they can reach. Connect can cut a server off for good (a retired or denied install), but a token already handed out stays valid until it expires
  • Installing the shared GitHub App on an organization consents for every Control Center server any member signs in on, not for one server
  • The bot is shared, as above: an organization cannot tell on GitHub which server acted as the bot
  • An organization that wants its own boundary registers its own GitHub App and runs its own Connect (Run a Connect server), or configures the App on its own servers
Connect How the server trusts its configuration
Hosted Verifies an Ed25519 signature against keys compiled into the build. Refuses an epoch lower than the highest it has seen (rollback)
Custom Pins the GitHub app id and client id, the Google and Linear client ids, and the Slack app and client ids on first use. A change pauses Connect sign-ins (pins_changed) until the server owner presses Trust new apps

The server’s Connect settings are server-owner only.

Operation Does
connect.status Mode, URL, lock, install id, health, configuration epoch and each lane’s source
connect.configure Sets hosted, custom (with url) or off
connect.test Fetches the configuration again and reports health
connect.confirmPins Accepts a custom Connect’s changed identifiers
connect.rotateKey Mints a new install key and a new install id (force replaces it even when a Connect could not retire the old one); see Rotate the install key

A workspace’s own choice has its own operations, each naming the workspace:

Operation Who Does
workspaceConnect.status Any member The choice, what it resolves to, health and each provider’s source. Install id and pending pins for admins only
workspaceConnect.set Workspace admin Sets inherit, hosted, custom (with url) or own
workspaceConnect.test Workspace admin Fetches the workspace’s Connect configuration again and reports health
workspaceConnect.confirmPins Workspace admin Accepts the workspace’s custom Connect’s changed identifiers

Sign-ins themselves use oauth.lanes, oauth.begin, oauth.status, oauth.complete, oauth.connections and oauth.disconnect. The person is always the signed-in caller.

  1. The server asks Connect to start the lane and receives the provider’s authorize URL, which it checks before showing it. GitHub always shows its account picker
  2. The person approves in the browser. The provider returns to Connect
  3. Connect shows what the server that started the sign-in will be able to do as the person, and for how long. Connect cannot tell who runs that server, so the page asks the person to continue only if they started the sign-in themselves, and to close it if someone sent them the link. When the browser is on another network than the one the sign-in was started from, the page says so: that is normal for a hosted server or another device, and it is also what phishing looks like. Cancel ends the sign-in: the provider’s code is never used. Each page answers once: an answer that did not come from the page Connect just showed is refused
  4. After Continue, Connect shows an 8-character code and a control-center://oauth-done link. Anyone who gets the code gets the access just approved, so it goes only where the sign-in was started
  5. The person types the code into the app, or follows the link. The server claims the sign-in with the code and its own proof of the request

A sign-in expires after 10 minutes. Five wrong codes end it. A link that this app did not start is refused with Sign-in not started here. Connect limits how many sign-ins one network address can start, and how often GitHub tokens are issued per person and server, per person across servers, per address and for the whole app. New sign-ins have a budget of their own, so they never hold up the renewals other people need. Past a limit a call is refused with rate_limited, and the server tries again later without signing anyone out. A sign-in past the person’s limit is undone at GitHub and refused.

Only the server owner can rotate the key, with Rotate key on the Control Center Connect card in Settings → Server → Single sign-on. There is no command for it. Rotating:

  • Signs everybody out of every lane that runs through Connect. For each Connect server the old key was used with, the server revokes the GitHub and Slack sign-ins it holds from there (a Google sign-in has nothing to revoke and lapses)
  • Retires the old install id at each of those Connect servers, signed with the old key and proven with one credential seal the server holds from that Connect. From then on Connect refuses every request made with the old key, so a seal or a copy of the old key taken from this server is useless, and the Slack workspaces bound to the old id are released so they can connect again. Tokens already handed out stay valid until they expire (an hour for a bot token, eight hours for a person’s). A Connect server this server holds no seal from has nothing to retire and is skipped
  • Then gives the server a new install key and a new install id
  • If a Connect server cannot be reached, or refuses to retire the old id, stops before switching keys and shows Connect could not retire the old key. Rotate anyway switches keys regardless; the old install id then stays usable at that Connect until its tokens expire, at most 8 hours for GitHub
  • Leaves sign-ins through the server’s own apps untouched
  • Needs the new install id added to a custom Connect’s allowlist
Code Meaning
hosted_unprovisioned This build has no hosted configuration key
signature The hosted configuration failed its signature check
rollback Connect served an older configuration than the server already saw
unreachable The server cannot reach Connect
install_blocked Connect does not allow this install id, or it was retired
pins_changed A custom Connect announced different app identifiers
protocol Connect answered in a form this server does not understand