Module 9 — Connecting Kavanah · Lesson 9.1
How Integrations Work
The integration card, what connecting actually grants, and the connection gate on agent tools
~11 min
What you'll learn
- Connect a provider by OAuth or by API key
- Explain who a connection belongs to and what scope it carries
- Describe the connection gate on agent tools
- Decide which integrations to connect first
Kavanah's value comes disproportionately from what it can see. Each integration is a decision to let it see one more thing — and each is also a credential, a scope, and something that will eventually need renewing. Understanding the shape once makes every specific integration lesson shorter.
The card, and the two connection styles
Open Settings and select the Integrations tab. Each provider is a card with a Connect button.
Most providers are OAuth: click Connect, complete the flow at the provider, and come back connected. You are granting Kavanah access to your account at that provider, with a specific scope you can usually see on the consent screen. Read it — the scope is what determines what the agent can do later.
Some providers are key-based: you paste an API key. Same result, different mechanism, and the key usually carries whatever permissions it was minted with rather than a scope you choose during connection.
A few are neither exactly. GitHub can be connected as a GitHub App install or by OAuth sign-in, with manual entry as a fallback — and repo selection happens afterwards, on the Dev surface rather than here. iCloud uses an app-specific password.
Who a connection belongs to
A connection is stored against your membership in this workspace. That has three consequences worth knowing up front.
It is per workspace. Connecting Gmail in one workspace does not connect it in another. This surprises everyone who belongs to several, once.
It is per person for personal accounts. Your mailbox connection is yours; a colleague's agent does not read your mail because you connected it.
And it carries YOUR permissions at the provider. A Google Drive connection sees the files your Google account can see. This is the right behaviour and it means a connection is exactly as powerful as the account behind it — which is worth remembering before connecting an admin account to something.
The connection gate
This is the mechanically important part.
The agent is not offered tools for providers that are not connected. They are stripped from its toolset rather than present-and-failing.
So when the agent says it cannot read your Notion, the honest reading is that it has no Notion tools, not that it is declining. Connect Notion and the tools appear.
This design exists so that a workspace which has not connected something sees an agent that behaves as though the capability does not exist, rather than one that constantly offers things that will fail. It also means the fastest diagnostic for 'the agent cannot do X' is to look at the Integrations tab, not to rephrase the request.
What to connect first
In order of how much they change the agent.
Calendar first. It is what makes scheduling real and capacity honest, and it is the connection whose absence is most visible in day-to-day answers.
Mail second. It is where commitments to people outside the team are made, and connecting it turns a large class of work — summarize, draft, chase — from advice into action.
Third, whatever holds your work today. If your engineering work is in GitHub, connect GitHub. If your tasks are in Jira or Asana or Monday, connect that, because it means you do not have to migrate everything before Kavanah is useful.
Everything else can wait until you have a specific reason. An integration connected 'to see what it does' is a credential with no owner and a renewal nobody remembers.
Testing and disconnecting
Cards show sync status, and you can test a connection from its card. Do this after connecting rather than assuming — a connection that completed the OAuth flow can still lack a scope you needed.
Disconnecting removes the credential. Note that disconnecting an integration falls into the destructive action category for the agent, so it is not something the agent does casually on your behalf.
And the connection's health is something to check periodically rather than only when something breaks. That is the subject of Lesson 9.6, and it is the maintenance nobody plans for.
Connect deliberately
- 1
Settings → Integrations. Of everything on this page, it changes the agent's day-to-day usefulness most.
- 2
Read the scope on the consent screen
The scope you grant determines what the agent can do later. It is worth ten seconds of reading.
- 3
Test the connection after making it
A completed OAuth flow can still be missing a scope you needed. Test rather than assume.
- 4
Check Integrations before concluding the agent cannot do something
Unconnected providers have their tools stripped entirely. This is the fastest diagnostic there is.
What to watch
- Connections in use
- How many connected providers are actually being read or written in a given month.
- Healthy signal: Most of them. An unused connection is a credential with a renewal nobody remembers and no benefit.
- Coverage of commitment-bearing systems
- Whether the systems where your team makes promises — mail, calendar, the tracker they actually use — are connected.
- Healthy signal: All of them. Each gap is a blind spot the agent cannot reason around.
Key takeaways
- ·Integrations are provider cards; most are OAuth, some are API keys, GitHub and iCloud have their own shapes.
- ·A connection is per workspace, per person for personal accounts, and carries your permissions at the provider.
- ·Unconnected providers have their agent tools STRIPPED — that is why 'it can't do that' is usually a connection question.
- ·Connect calendar, then mail, then whatever holds your work today.
- ·Test after connecting; a completed OAuth flow can still lack a scope you needed.
Next: the biggest suite of them — Google Workspace, and what each piece actually gives you.