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 seven per-connector pages become setup instructions rather than concepts.

Available connectors#

The seven connectors
Connector	You provide	Delivery
Slack	An OAuth authorisation	Push
GitHub	An app installation on your organisation	Push
GitLab	A group path and a group access token with the Owner role	Poll, 10 minutes
Okta	Your org domain and an Okta API Services app	Push
Google Workspace	Domain-wide delegation and an admin to impersonate	Poll, 10 minutes
Microsoft Entra ID	Admin consent from a tenant administrator	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, one Google service account and one Microsoft Entra app registration, so your side of the setup is authorising ours rather than building your own. Okta and GitLab take a read-only token you create; AWS takes a role you create.

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, GitLab group, Okta domain, Google domain, Microsoft tenant 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 app's client ID, no secret	Not applicable
GitLab	Your group access token	Yes, AES-256-GCM
GitHub	An installation id, no token	Not applicable
Google Workspace	The admin email to impersonate	Not applicable
Microsoft Entra ID	Your tenant id, no token	Not applicable
AWS	A role ARN	Not applicable

Only Slack, Okta and GitLab hold a long-lived secret. The other four are designed so that no reusable credential is held: GitHub and Entra ID tokens are minted per operation from Governax's own app registrations, 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
GitLab	Nothing. Delete the group access token in GitLab to fully revoke.
Google Workspace	Nothing. Remove the delegation in your Admin console to fully revoke.
Microsoft Entra ID	Nothing. Remove Governax under Enterprise applications in the Entra admin centre 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 seven connectors depend on the same queue and scheduling infrastructure. Details of the pipeline are in How events reach the ledger.