Integration Connections
Manage the OAuth tokens and per-account configuration that intents use to deliver insights.
A connection is your authorized link to one third-party account. While Integrations explains the providers themselves, this page covers the lifecycle of the connections that intents target — listing them, configuring per-account defaults, refreshing expired tokens, and removing connections you no longer trust.
Where Connections Live
- Index:
/integration-connectionslists every connection in your workspace - New:
/integration-connections/newwalks you through authorizing a provider - Detail:
/integration-connections/[id]lets you edit, re-authorize, or delete a single connection
A connection always belongs to a single provider but multiple connections per provider are supported (e.g. personal and work GitHub accounts).
Connection Status
Each connection carries a status:
| Status | Meaning |
|---|---|
active | Token is valid; intents can deliver through this connection |
expired | Token has expired — re-authorize from the detail page |
error | The last delivery hit a provider error (4xx/5xx); inspect the linked insight |
revoked | The connection was revoked on the provider side; re-authorize to restore access |
When a connection moves out of active, intents that target it will fail at delivery time and the resulting insight will surface the error in its integration log.
Per-Connection Config
Most providers store configuration on the connection rather than the intent. This keeps intents portable across accounts. Examples:
- GitHub — default repo, default labels, default assignee
- Slack — default channel, posting username
- Notion — target database ID, default property mappings
- Linear — default team and workflow state
- Trello — board and list IDs
When you wire an intent to a connection, the intent inherits these defaults and can override individual fields.
Re-authorizing
Open /integration-connections/[id] and click Re-authorize. The flow:
- Redirects to the provider's OAuth consent screen
- Returns to SpokeDo with a fresh access/refresh token pair
- Replaces the existing token in place — the connection's ID, name, and config are preserved
This is the safe path: deleting and recreating a connection would orphan every intent that referenced the old ID.
Deleting Connections
Deletion is destructive and only blocked when intents reference the connection. The detail page shows the count of dependent intents; you must repoint or delete those intents first.
Best Practices
- Name connections explicitly (
github-personal,slack-eng-channel) — the name is what intents pick from - Re-authorize on
expired; only delete when the underlying account is being retired - Audit
last_used_atperiodically and remove connections that haven't fired in months - Keep one connection per credential boundary (account, workspace, team) rather than sharing one across teams