> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onyx.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Slack Indexed

> Set up the Slack Indexed connector

## How it works

The Slack connector indexes all public channels for a given workspace.

To index private channels, add the Slack App to the private channel.

For Slack Enterprise Grid orgs, a single install covers every workspace in the org.
See [Enterprise Grid setup](#enterprise-grid-setup) below.

## Setting up

### Authorization

<Steps>
  <Step title="Admin requirement">
    **Note: You must be an admin of the Slack workspace to set up the connector**
  </Step>

  <Step title="Navigate to Slack Apps">
    Navigate and sign in to [https://api.slack.com/apps](https://api.slack.com/apps).
  </Step>

  <Step title="Create new Slack app">
    Create a new Slack app:

    * Click the **Create New App** button in the top right.
    * Select **From an app manifest** option.
    * Select the relevant workspace from the dropdown and click **Next**.

    <img className="rounded-image" src="https://mintcdn.com/danswer/24Ocig51qMqahMaT/assets/admins/connectors/slack/SlackApp.png?fit=max&auto=format&n=24Ocig51qMqahMaT&q=85&s=34db1121037811370fb9b3cf38985fa8" alt="Slack app creation flow with manifest option selected" width="1137" height="862" data-path="assets/admins/connectors/slack/SlackApp.png" />
  </Step>

  <Step title="Configure app manifest">
    Select the "YAML" tab, paste the following manifest into the text box, and click **Next**:

    ```
    display_information:
      name: OnyxConnector
      description: ReadOnly Connector for indexing Onyx
    features:
      bot_user:
        display_name: OnyxConnector
        always_online: false
    oauth_config:
      scopes:
        bot:
          - channels:history
          - channels:read
          - groups:history
          - groups:read
          - channels:join
          - im:history
          - users:read
          - users:read.email
          - usergroups:read
    settings:
      org_deploy_enabled: false
      socket_mode_enabled: false
      token_rotation_enabled: false
    ```
  </Step>

  <Step title="Create the app">
    Click the **Create** button.
  </Step>

  <Step title="Navigate to OAuth permissions">
    In the app page, navigate to the **OAuth & Permissions** tab under the **Features** header.
  </Step>

  <Step title="Copy OAuth token">
    Copy the **Bot User OAuth Token**, this will be used to access Slack.
  </Step>
</Steps>

<img className="rounded-image" src="https://mintcdn.com/danswer/24Ocig51qMqahMaT/assets/admins/connectors/slack/SlackBotToken.png?fit=max&auto=format&n=24Ocig51qMqahMaT&q=85&s=d6e68c50a4b40bb36305b7dadf176b2a" alt="Slack OAuth & Permissions page showing Bot User OAuth Token" width="1626" height="1066" data-path="assets/admins/connectors/slack/SlackBotToken.png" />

### Indexing

<Steps>
  <Step title="Navigate to connector">
    Navigate to the Connector Dashboard and select the **Slack** Connector.
  </Step>

  <Step title="Provide credentials">
    Place the **Bot User OAuth Token** under **Step 1 Provide Credentials**

    <img className="rounded-image" src="https://mintcdn.com/danswer/24Ocig51qMqahMaT/assets/admins/connectors/slack/SlackConnectorSetting.png?fit=max&auto=format&n=24Ocig51qMqahMaT&q=85&s=47cc70a242bc75db2835d26c57e0ba86" alt="Onyx Slack connector settings showing Bot User OAuth Token input" width="1427" height="1142" data-path="assets/admins/connectors/slack/SlackConnectorSetting.png" />
  </Step>

  <Step title="Set workspace ID and connect">
    Set the **Workspace ID** (see below) and click **Connect**.
  </Step>
</Steps>

<img className="rounded-image" src="https://mintcdn.com/danswer/24Ocig51qMqahMaT/assets/admins/connectors/slack/SlackId.png?fit=max&auto=format&n=24Ocig51qMqahMaT&q=85&s=540e416a4bdd5d8e88b9872bea15660c" alt="Locating the Slack workspace ID in the app configuration" width="680" height="519" data-path="assets/admins/connectors/slack/SlackId.png" />

**Note:** The first indexing pulls all of the public channels and takes longer than future updates.

## Enterprise Grid setup

If your Slack instance is an [Enterprise Grid](https://slack.com/help/articles/360000281563)
org with multiple workspaces,
you go through the app-creation flow once at the org level and use a single org-level bot token in Onyx.
Slack still requires the org admin to choose which workspaces the bot is deployed to (it is not auto-deployed to every
workspace just because the app is approved at the org level).
Onyx detects Grid automatically from the bot token and indexes every workspace the bot has been deployed to.

<Note>
  You must be an **Org Owner** or **Org Admin** of the Slack Enterprise Grid org to do the org-level install.
</Note>

### What changes vs the single-workspace setup

* The app manifest must enable org-level deploys and include the `team:read` scope.
* You install the app to the **organization** once (a single OAuth approval as Org Admin), but you must also pick
  which workspaces in the org the bot is deployed to — Onyx can only index the workspaces the bot is actually a member
  of.
* Channel links in indexed documents resolve to the correct per-workspace URL.
* Document permissions for public channels are scoped to the users in the workspaces the channel is shared into
  (not the entire org), so a user in Workspace A cannot see Workspace B's public channel documents in Onyx.

### Authorization (Grid)

<Steps>
  <Step title="Create a new Slack app">
    On [https://api.slack.com/apps](https://api.slack.com/apps), click **Create New App** → **From an app manifest**.
    Select **any** workspace inside your Grid org as the development workspace (the manifest below promotes the app to
    org-level on install).
  </Step>

  <Step title="Use the Grid manifest">
    Paste the following manifest. The two differences from the single-workspace manifest are `org_deploy_enabled:
            true` and the added `team:read` bot scope:

    ```yaml theme={null}
    display_information:
      name: OnyxConnector
      description: ReadOnly Connector for indexing Onyx
    features:
      bot_user:
        display_name: OnyxConnector
        always_online: false
    oauth_config:
      scopes:
        bot:
          - channels:history
          - channels:read
          - groups:history
          - groups:read
          - channels:join
          - im:history
          - users:read
          - users:read.email
          - usergroups:read
          - team:read
    settings:
      org_deploy_enabled: true
      socket_mode_enabled: false
      token_rotation_enabled: false
    ```
  </Step>

  <Step title="Install to the organization">
    Open **OAuth & Permissions** and click **Install to Organization** (not "Install to Workspace").
    Approve the request as an Org Admin.
    This is a single OAuth approval — it does **not** deploy the bot to any workspace yet.
  </Step>

  <Step title="Deploy the bot to each workspace you want indexed">
    Slack does not auto-deploy org-approved apps to every workspace.
    Open the Grid org admin panel (`https://<your-org>.enterprise.slack.com/admin`) → **Apps** → **Onyx Connector**,
    and select the workspaces the bot should be deployed to.
    Without this step `auth.teams.list` returns zero workspaces and Onyx will only see the workspace the app was
    developed in.
  </Step>

  <Step title="Copy the org-level bot token">
    Back on the app's **OAuth & Permissions** page, copy the **Bot User OAuth Token**.
    The token starts with `xoxb-` just like a regular bot token but carries org-level permissions.
  </Step>
</Steps>

### Indexing (Grid)

The connector setup in Onyx is identical to the single-workspace flow — paste the bot token and click **Connect**.
Onyx inspects `auth.test()` on the token; if `enterprise_id` is present it switches to Grid mode automatically:

* Enumerates workspaces via `auth.teams.list`
* Lists channels per workspace via `conversations.list?team_id=...` and dedupes org-shared channels
* Resolves the per-workspace URL via `team.info` for channel link building
* Builds per-workspace user-email sets for public-channel permission scoping

### Permission scoping behavior

| Channel type                                      | ACL on Onyx                                                  |
| ------------------------------------------------- | ------------------------------------------------------------ |
| Public channel in one workspace                   | Granted to users of that workspace                           |
| Org-shared public channel (`is_org_shared: true`) | Granted to the union of users across all `shared_team_ids`   |
| Private channel                                   | Granted to the channel's actual members (workspace-agnostic) |
| Union exceeds 5000 users or all teams unknown     | Falls back to `is_public=true` so the doc stays searchable   |

### Troubleshooting (Grid)

<AccordionGroup>
  <Accordion title="Validation error: missing `team:read` scope">
    The Grid path requires `team:read` to enumerate workspaces. Add the scope to the manifest,
    reinstall the app to the organization, and copy the new bot token into Onyx.
  </Accordion>

  <Accordion title="Onyx only indexes channels from one workspace">
    `auth.teams.list` only returns workspaces the bot has been added to.
    Open the Grid org admin panel → **Apps** → **Onyx Connector** and add it to every workspace you want indexed,
    then trigger a new index attempt.
  </Accordion>

  <Accordion title="A user from another workspace can search a workspace's public-channel content">
    Only happens when the per-workspace user union exceeds `5000`.
    Above that limit Onyx falls back to marking the doc public so it stays accessible;
    the same fallback applies when none of the channel's workspaces are in Onyx's cache (for example a workspace added
    to the Grid org after the connector was set up). Re-saving the credential re-builds the workspace cache.
  </Accordion>
</AccordionGroup>