Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

docs: organizations' connector apps and service switches

Petr Bauchcb88bea7633f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b93d180be..1d2eac972 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -113,6 +113,30 @@ version of their own to them without also giving them a release of their own.
switch-core pods as written, so they can run on a node group of their own,
such as one kept for load tests. Both are empty by default, which places the
pods as before.
+- **Organizations set up their own connector apps and switch services for
+ their workspaces, behind `organization_connector_apps`, off by default.**
+ With the flag on (and `service_connections`), the dashboard's Organization
+ page gains two sections for organization admins:
+ - **Connectors.** An organization saves its own GitHub App, Google client
+ or Airtable integration, checked with the vendor as the operator's are.
+ Every workspace in the organization then signs in, is issued and is
+ refreshed through it rather than the server's. An organization's app
+ that stops working makes the service unavailable in its workspaces,
+ with the reason, and never falls back to the server's. A workspace's
+ service listing says whose app it goes through (`app_source`).
+ - **Services.** An organization switches each service on or off for its
+ workspaces. Unlocked, its setting applies where a workspace admin hasn't
+ set the service themselves; locked, it applies everywhere and workspace
+ admins can't change it. Wherever a change leaves a service off, the
+ tokens issued for it there are revoked. A workspace admin can drop their
+ own switch (`DELETE /gateway/workspace/services/{service}`) to take the
+ organization's setting.
+
+ Every change is recorded in the organization's audit log. The platform
+ operator has no say in an organization's apps or services unless they are
+ one of its admins. With the flag off, nothing changes: the routes aren't
+ mounted and no workspace consults its organization. The migration adds
+ two empty tables either way.
- **The `[CONN]` log lines say when a client fell back to the event stream.**
`/events` takes optional `fallback` and `fallback_close_code` parameters,
and the `[CONN] opened` and `[CONN] reattached` lines end with
diff --git a/docs/old/airtable-setup.md b/docs/old/airtable-setup.md
index 207d9d4c3..cb6545025 100644
--- a/docs/old/airtable-setup.md
+++ b/docs/old/airtable-setup.md
@@ -149,3 +149,15 @@ next token requests:
- Reconnecting never narrows what a connection reaches: the bases of every
grant the person has not removed in Airtable still count (see "What people
do").
+
+## An organization's own Airtable integration
+
+With the `organization_connector_apps` flag on (with `service_connections`),
+an organization's admins can save its own under **Organization**,
+**Connectors** in the dashboard, with the same callback, checks and
+encryption as above. Every workspace in that organization then signs in
+through the organization's integration instead of the server's; the others keep
+using the server's. If the organization's integration stops working, its
+workspaces see Airtable as unavailable, with the reason, rather than falling
+back to the server's. Removing it sends them back to the server's integration, and
+people connected through it reconnect once. The flag is off by default.
diff --git a/docs/old/github-app-setup.md b/docs/old/github-app-setup.md
index fcefebd10..52c129197 100644
--- a/docs/old/github-app-setup.md
+++ b/docs/old/github-app-setup.md
@@ -112,6 +112,18 @@ restart switch-core. It is the same App, so nobody reconnects. Copying is
refused while the file's `origin` differs from `GATEWAY_PUBLIC_URL`, since a
saved App is called back at `GATEWAY_PUBLIC_URL`.
+## An organization's own GitHub App
+
+With the `organization_connector_apps` flag on (with `service_connections`),
+an organization's admins can save its own under **Organization**,
+**Connectors** in the dashboard, with the same callback, checks and
+encryption as above. Every workspace in that organization then signs in
+through the organization's App instead of the server's; the others keep
+using the server's. If the organization's App stops working, its
+workspaces see GitHub as unavailable, with the reason, rather than falling
+back to the server's. Removing it sends them back to the server's App, and
+people connected through it reconnect once. The flag is off by default.
+
## Several replicas
Sign-ins in progress are kept in the database, and a change to the App
diff --git a/docs/old/google-workspace-setup.md b/docs/old/google-workspace-setup.md
index 43dc6fd4c..a506c7dbc 100644
--- a/docs/old/google-workspace-setup.md
+++ b/docs/old/google-workspace-setup.md
@@ -171,3 +171,15 @@ its app has passed Google's review.
- A granted agent's token is its owner's own, shared by every agent they
grant; it cannot be narrowed or revoked per agent. Turning an agent off stops
its sessions within an hour; disconnecting stops every agent at once.
+
+## An organization's own Google client
+
+With the `organization_connector_apps` flag on (with `service_connections`),
+an organization's admins can save its own under **Organization**,
+**Connectors** in the dashboard, with the same callback, checks and
+encryption as above. Every workspace in that organization then signs in
+through the organization's client instead of the server's; the others keep
+using the server's. If the organization's client stops working, its
+workspaces see Google Workspace as unavailable, with the reason, rather than falling
+back to the server's. Removing it sends them back to the server's client, and
+people connected through it reconnect once. The flag is off by default.