Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cloudflare/cloudflare-os/llms.txt

Use this file to discover all available pages before exploring further.

The Slack Gatekeeper connects Cloudflare OS to Slack workspaces via OAuth, giving agents and Gadgets read access to channels, direct messages, threads, workspace members, and full-text search. It uses a user token (xoxp-…) so the agent sees exactly what the connecting user can see — including private channels, DMs, and multi-party DMs — without ever exceeding the user’s own permissions.
The Slack Gatekeeper is read-only. It never sends messages or modifies Slack data. All access is observational — ideal for agents that need to understand team context, search past conversations, or monitor a channel’s activity.

​
Capabilities

The Slack Gatekeeper provides access at three levels of granularity. You can introduce an agent to an entire workspace, a single conversation (channel or DM), or a specific thread.
GranularityResource URLSession type
Workspace — all channels, DMs, members, and searchhttps://* (catch-all)SlackWorkspaceSession
Conversation — a single channel, DM, or group DMhttps://app.slack.com/client/:teamId/:conversationIdSlackConversation
Thread — a single message threadhttps://*.slack.com/archives/:conversationId/:messageIdSlackThread
More-specific conversation and thread URLs take precedence over a workspace-wide grant. Channels and DMs share the “Conversation” grant type.

​
OAuth Scopes by Resource

The Slack Gatekeeper requests user token scopes (user_scope), not bot scopes. Scopes are requested only for the resource granularity being connected:
GrantUser token scopes
Workspaceteam:read, channels:read, channels:history, groups:read, groups:history, im:read, im:history, mpim:read, mpim:history, search:read, users:read
Conversationchannels:read, channels:history, groups:read, groups:history, im:read, im:history, mpim:read, mpim:history, search:read, users:read
Threadchannels:history, groups:history, im:history, mpim:history, users:read
users:read is always requested for connected-account display and resolving user mentions to readable names.

​
Setting Up Slack OAuth

1

Create a Slack app

  1. Go to api.slack.com/apps and click Create New App.
  2. Choose From scratch.
  3. Give it a name (e.g., “My Company OS”) and select the workspace you are building for.
  4. Click Create App.
2

Configure OAuth redirect URL

In the left sidebar, go to OAuth & Permissions.Under Redirect URLs, click Add New Redirect URL and enter:
  • Local dev: http://localhost:8787/gatekeeper/slack/oauth
  • Production: ${PUBLIC_BASE_URL}/gatekeeper/slack/oauth
Click Save URLs.
3

Enable token rotation

On the same OAuth & Permissions page, scroll down to Token Rotation and enable it.Token rotation produces short-lived tokens (~12 hours) that are refreshed automatically via oauth.v2.access?grant_type=refresh_token. Non-rotating tokens also work as a fallback, but rotation is recommended for security.
4

Add user token scopes

Still on OAuth & Permissions, scroll to User Token Scopes (not Bot Token Scopes). Add the scopes appropriate for the resources you plan to offer.At minimum, add the workspace scopes listed above. You can limit to conversation or thread scopes if you only plan to offer narrower grants.
5

Configure credentials

In the left sidebar, go to Basic Information and copy the Client ID and Client Secret from the App Credentials section.For local development, set these in the repo-root .dev.vars:
.dev.vars
SLACK_CLIENT_ID=your-client-id
SLACK_CLIENT_SECRET=your-client-secret
The dev server maps SLACK_CLIENT_ID / SLACK_CLIENT_SECRET into the Worker’s CLIENT_ID / CLIENT_SECRET automatically.
6

Verify the setup

  1. Start the application in dev mode (pnpm dev-server + pnpm dev-client).
  2. Create or open a Gadget and navigate to the Connections tab.
  3. Click + New Connection and choose Slack.
  4. Connect your Slack account — you will be redirected to Slack’s authorization page.
  5. After approving, the tab closes and you are back in the Gadget.
  6. Paste a Slack conversation or thread URL, or choose a workspace-level grant.

​
What Agents Can Do

  • getInfo — read workspace name and metadata
  • listChannels — list public and private channels the user is a member of
  • listDirectMessages — list DMs and group DMs
  • listUsers — list workspace members
  • getUser — fetch a user’s profile
  • getConversation — open a specific conversation by ID
  • search — full-text search across the entire workspace
List and search methods return paginated Cursor objects. User mentions in messages are resolved to readable names automatically.

​
Example Agent Prompts

"Summarize what was discussed in #engineering-standup this week."

"Search the #sales channel for mentions of the Acme deal from the last month."

"Who has been most active in #product-feedback this quarter?"

​
Sharing and Observers

Because the Slack Gatekeeper uses the connecting user’s own token, the agent sees exactly the channels and messages that user can see. Sharing a Gadget that uses a Slack connection requires the collaborator to connect their own Slack account. The collaborator’s token is used when they open the Gadget — they cannot see messages from channels they are not a member of.

Build docs developers (and LLMs) love

Get started for freeTalk to us