Connecting a tool

On this page

Available connectors
One connection, one entity
How credentials are stored
What happens when you connect
What disconnecting does
Connection health

Rules that apply to every connector. Read this once and the five per-connector pages become setup instructions rather than concepts.

Available connectors#

The five connectors
Connector	You provide	Delivery
Slack	An OAuth authorisation	Push
GitHub	An app installation on your organisation	Push
Okta	Your org domain and a read-only API token	Push
Google Workspace	Domain-wide delegation and an admin to impersonate	Poll, 10 minutes
AWS	A cross-account IAM role	Poll, 10 minutes

You never register an application yourself. Governax operates one Slack app, one GitHub App and one Google service account, so your side of the setup is authorising ours rather than building your own.

One connection, one entity#

A connector belongs to exactly one entity, and its events land only in that entity's ledger. An external account, meaning one Slack workspace, GitHub organisation, Okta domain, Google domain or AWS account, can be connected to only one entity at a time across all of Governax.

Both refusals return 409 WORKSPACE_ALREADY_CONNECTED
Situation	What to do
The account is connected to a different organisation	Refused regardless of status. Contact support if this is unexpected, for example after a trial under another account.
The account is connected to another entity in your organisation	Disconnect it there first, then connect it here.

How credentials are stored#

What each connector stores
Connector	Stored	Encrypted at rest
Slack	An access token	Yes, AES-256-GCM
Okta	Your API token	Yes, AES-256-GCM
GitHub	An installation id, no token	Not applicable
Google Workspace	The admin email to impersonate	Not applicable
AWS	A role ARN	Not applicable

Only Slack and Okta require a long-lived secret. The other three are designed so that no reusable credential is held: GitHub tokens are minted per operation, Google access is authorised on your side and can be withdrawn there, and AWS access is a role your account grants and can revoke.

What happens when you connect#

The credential is verified before the connection is saved. A connector that cannot actually read is reported at connect time rather than failing silently later.
A baseline snapshot is taken. Governax records who already has access, so the ledger has a starting position rather than only recording changes from now on. These arrive as access.baseline_observed events.
The baseline never blocks the connection. If the snapshot fails, the connection still succeeds and events still flow.

Reconnecting the same account reuses the same connection. Baseline events carry deterministic identifiers, so re-running one never duplicates history, and the polled connectors keep their position so a reconnect does not re-import everything.

What disconnecting does#

Disconnecting stops ingestion. It never removes anything already recorded: the ledger is append-only, so every event captured while the connector was live stays exactly where it is, and remains verifiable.

What each connector does on disconnect
Connector	Action taken on the tool's side
Slack	Revokes the token, and erases the stored copy
GitHub	Uninstalls the app from your organisation
Okta	Deactivates and deletes the Event Hook it created
Google Workspace	Nothing. Remove the delegation in your Admin console to fully revoke.
AWS	Nothing. Delete the IAM role in your account to fully revoke.

A tool can also disconnect itself. Uninstalling the Slack app or the GitHub App from that tool records integration.disconnected_remotely and marks the connection dead, so the interface does not keep showing a healthy badge for something that stopped working.

Connection health#

Each connection surfaces:

Status, connected or disconnected
Which external account it is bound to
When it was connected, and by whom
The time of the last event received
The last error, if there was one

One shared dependency worth knowing about for anyone reviewing architecture: all five connectors depend on the same queue and scheduling infrastructure. Details of the pipeline are in How events reach the ledger.