Slack OAuth Integration Setup Guide

This guide walks you through setting up a Slack OAuth integration for SurfSense.

Step 1: Create a New Slack App

1. Navigate to api.slack.com/apps
2. Click "Create New App"
3. Select "From scratch" to manually configure your app

Step 2: Name App & Choose Workspace

1. Enter App Name: SurfSense
2. Select the workspace to develop your app in
3. Click "Create App"

⚠️ You won't be able to change the workspace later. The workspace will control the app even if you leave it.

Step 3: Get App Credentials

After creating the app, you'll be taken to the Basic Information page. Here you'll find your credentials:

1. Copy your Client ID
2. Copy your Client Secret (click Show to reveal)

⚠️ Never share your app credentials publicly.

Step 4: Configure Redirect URLs

1. In the left sidebar, click "OAuth & Permissions"
2. Scroll down to Redirect URLs
3. Click "Add New Redirect URL"
4. Enter: https://localhost:8000/api/v1/auth/slack/connector/callback
5. Click "Add", then "Save URLs"

Step 5: Configure Bot Token Scopes

On the same OAuth & Permissions page, scroll to Scopes and add the following Bot Token Scopes:

Click "Add an OAuth Scope" to add each scope.

Step 6: Enable Public Distribution

1. In the left sidebar, click "Manage Distribution"
2. Under Share Your App with Other Workspaces, ensure distribution is enabled
3. You can use the "Add to Slack" button or Sharable URL to install the app

Running SurfSense with Slack Connector

Add the Slack environment variables to your Docker run command:

docker run -d -p 3000:3000 -p 8000:8000 \
  -v surfsense-data:/data \
  # Slack Connector
  -e SLACK_CLIENT_ID=your_slack_client_id \
  -e SLACK_CLIENT_SECRET=your_slack_client_secret \
  -e SLACK_REDIRECT_URI=https://localhost:8000/api/v1/auth/slack/connector/callback \
  --name surfsense \
  --restart unless-stopped \
  ghcr.io/modsetter/surfsense:latest