> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kowalah.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Chat platform security
> How the Kowalah Agent installs into Slack, Teams, and Google Chat, what permissions it requests and why, and the controls available to workspace admins.
The [Kowalah Agent](/integrations/agent/overview) 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](/security/data-and-access) 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](/integrations/agent/setup-slack), [Teams](/integrations/agent/setup-teams), and [Google Chat](/integrations/agent/setup-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.
| Scope | Why it's needed |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `app_mentions:read` | Detect when a user `@mentions` Kowalah — the trigger for everything |
| `chat:write` | Post Kowalah's replies into the thread |
| `channels:history`, `groups:history`, `im:history`, `mpim:history` | Read 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:read` | Resolve basic channel/conversation metadata needed to reply in the right place |
| `users:read`, `users:read.email` | Match the Slack user to their linked Kowalah account |
| `reactions:write` | Add 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
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.
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.
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.
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.