Skip to main content
The Kowalah Agent lives in your chat platform and responds when someone directly addresses it — either by @mention in a channel or by messaging it directly. This page covers how it’s installed, what permissions it asks for and why, and what your workspace admins control. All data access still goes through the same Kowalah Client MCP and access-control model described elsewhere in this section — the chat platform is only the surface where conversations happen.

​
How it’s installed

A workspace admin installs the Kowalah app once, through the platform’s standard app-installation flow (Slack OAuth, Teams app catalog, or Google Chat). Individual users then link their own Kowalah account the first time they interact with the Agent. Until a user has linked their account, the Agent will not return any data — it asks them to link first. See the setup guides for Slack, Teams, and Google Chat.

​
It only responds when directly addressed

The Agent is not an always-listening bot. It responds in exactly two situations:
  • When a user @mentions it in a channel or space it’s been added to, or
  • When a user messages it directly (a DM started from the Kowalah app in Slack, Teams, or Google Chat).
In both cases the user is deliberately addressing the Agent. Beyond that, it does not passively read, monitor, or archive channel activity, and it does not ingest or index your message history. It reads the message it was addressed in (and the thread or DM it’s participating in) to understand context, and nothing more.

​
Slack permissions explained

Slack apps request OAuth scopes at install time. Here is every scope the Kowalah app requests and why it needs it.
ScopeWhy it’s needed
app_mentions:readDetect when a user @mentions Kowalah — the trigger for everything
chat:writePost Kowalah’s replies into the thread
channels:history, groups:history, im:history, mpim:historyRead the message it was mentioned in and the thread it’s replying within, so it has the context of the conversation
channels:read, groups:read, im:read, mpim:readResolve basic channel/conversation metadata needed to reply in the right place
users:read, users:read.emailMatch the Slack user to their linked Kowalah account
reactions:writeAdd a quick acknowledgement reaction (for example, while it’s working)
The *:history scopes are what security teams most often ask about. Slack grants these at the conversation level, but the Agent only reads the thread it has been brought into — it does not bulk-read or store channel history. The scopes exist so it can understand the conversation you’ve @mentioned it in; they are not used to crawl your workspace.

​
Teams and Google Chat

  • Microsoft Teams: the app is installed within your tenant and uses Teams’ native identity and messaging permissions. It can be used as a personal chat, in a team, or in a group chat. It does not request file-access permissions.
  • Google Chat: the Agent operates under Google Chat’s native app permission model, responding to direct messages and to @mentions in spaces it has been added to.
In all three platforms, the same principle holds: the Agent only sees the conversations it’s explicitly invited into, and only returns Kowalah data the linked user is entitled to.

​
Identity and per-message scoping

Each message is handled independently:
  1. The Agent reads which user sent the message.
  2. It resolves that user’s linked Kowalah identity and organization.
  3. It answers using only that user’s data access.
This means two people in the same thread get answers scoped to their own organizations and roles. A prompt-injection attempt cannot make the Agent return another organization’s data, because the data boundary is enforced server-side by the user’s token — not by anything in the conversation.

​
What admins control

Install and uninstall

Workspace admins approve the app at install and can remove it at any time through the platform’s own admin tools. Removing the app immediately cuts off its access.

Where it can be used

The Agent works in channels and spaces it’s been added to (when @mentioned) and in direct messages users start with it. It never responds passively. Admins decide where it’s present.

Who can use it

Only users who have linked a valid Kowalah account get data. Removing or disabling a user in your workspace, or in Kowalah, ends their access.

Revoke access

A user’s Kowalah access token can be revoked centrally. Revoked and expired tokens are rejected on the very next request.
Because access is per user and enforced on every request, your normal joiner/mover/leaver process already governs the Agent: when someone loses access in your identity provider or in Kowalah, they lose access to the Agent.