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

# Slack

> Connect your Slack workspace or Enterprise Grid organization to Oleria to continuously discover and map who has access across your channels, user groups, files, and workspaces.

Connect Slack to Oleria to gain continuous visibility into who has access across your Slack workspace or Enterprise Grid organization. Oleria reads identity, access, and (on Enterprise Grid) audit data from the Slack Web API, so you can see every account, channel, file, user group, and access change in one place. This page provides step-by-step guidance for connecting Slack to Oleria.

## What Oleria discovers

Once connected, Oleria continuously discovers and maps the following from your Slack workspace or organization:

* **Accounts** - every member of the workspace, including humans, bots, and installed apps, along with account status, workspace role (owner, admin, member, guest), and admin flags.
* **Channels** - public and private channels and their membership. Direct messages and group DMs are intentionally excluded.
* **Resources** - files shared in Slack channels, along with the channels and uploader that have access to each file. With a bot token only, discovery is limited to files in channels the bot has been added to; adding a user token extends this to every public channel in the workspace, regardless of bot membership.
* **User groups** - native Slack user groups and the membership relationships between users, groups, and channels.
* **Workspaces** - on Enterprise Grid, each workspace in the organization, with channels and user groups grouped beneath their parent workspace.
* **System roles** - Enterprise Grid system role assignments (Grid only).
* **Audit activity** - organization-wide audit events such as membership changes, access configuration changes, and user lifecycle events (Grid only).

<Note>
  Core discovery (accounts, channels, user groups, resources) works on any Slack plan. Workspace enumeration, installed-app inventory, system roles, and audit activity require an **Enterprise Grid** plan and are only collected when you connect at the organization level. Full resource (file) coverage additionally depends on connecting a user token, independent of plan or scope - see [Prerequisites](#prerequisites).
</Note>

## Prerequisites

* **Workspace Owner** for a single workspace, or **Organization Owner / Admin** for an Enterprise Grid organization. Ordinary workspace admins cannot grant the `admin.*` scopes required for Grid discovery.
* An **Organization Owner**, specifically, if you want audit activity. Slack's Audit Logs API does not accept Organization Admin tokens, so an Admin-authorized install cannot enable audit log discovery even though it can grant every other Grid scope.
* A **user token**, for every connection - single workspace or Enterprise Grid. Oleria's connection form requires one; it's not optional.
* Permission to create and install a Slack app in the workspace or organization. If your workspace has an app-approval policy, an admin must approve the app before it can be installed.
* An **Enterprise Grid** subscription if you want installed-app inventory, system roles, and audit activity. Account, channel, user group, and resource discovery work on any plan.

## Choose your integration scope

Oleria connects at one of two scopes, which determines the credentials you create:

| Scope                              | When to use                                                                   | Credentials needed                                                                                                                                                                                                    |
| :--------------------------------- | :---------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Single workspace** (default)     | A single Slack workspace, including one workspace under a Grid organization.  | Bot token and user token                                                                                                                                                                                              |
| **Enterprise Grid (organization)** | A Grid organization spanning multiple workspaces, with admin and audit depth. | User token (with `admin.*` scopes, authorized by an Organization Owner for audit access); bot token optional - channel and user group discovery normally read from it, falling back to the user token if it's omitted |

## Create a Slack app and generate tokens

Oleria connects using tokens issued from a Slack app that you create and install in your workspace or organization.

<Steps>
  <Step title="Create the app">
    Go to the [Slack API apps page](https://api.slack.com/apps) and select **Create New App** → **From scratch**. Give it a recognizable name such as `Oleria Connector`.

    * For a **single workspace**, select that workspace as the development workspace.
    * For **Enterprise Grid**, sign in as an Organization Owner/Admin and select the organization so the app can be installed org-wide.
  </Step>

  <Step title="Add bot token scopes">
    Open **OAuth & Permissions** → **Scopes** → **Bot Token Scopes** and add the following. These power core discovery on every plan:

    | Scope              | Used for                                                |
    | :----------------- | :------------------------------------------------------ |
    | `team:read`        | Workspace name, domain, and plan detection              |
    | `users:read`       | Discovering accounts (users, bots, and apps)            |
    | `users:read.email` | Reading account email addresses                         |
    | `usergroups:read`  | Discovering Slack user groups and their members         |
    | `channels:read`    | Discovering public channels and their membership        |
    | `groups:read`      | Discovering private channels and their membership       |
    | `files:read`       | Discovering files in channels the bot has been added to |
  </Step>

  <Step title="Add user token scopes">
    Under **OAuth & Permissions** → **Scopes** → **User Token Scopes**, add the following:

    | Scope                      | Used for                                                                                                    | Required for                         |
    | :------------------------- | :---------------------------------------------------------------------------------------------------------- | :----------------------------------- |
    | `search:read`              | Full resource (file) discovery across every public channel, regardless of bot membership                    | Single workspace and Enterprise Grid |
    | `admin.users:read`         | Enumerating accounts across the organization                                                                | Enterprise Grid only                 |
    | `admin.teams:read`         | Discovering the workspaces in the organization                                                              | Enterprise Grid only                 |
    | `admin.conversations:read` | Discovering channels, including shared channels                                                             | Enterprise Grid only                 |
    | `admin.apps:read`          | Installed-app inventory                                                                                     | Enterprise Grid only                 |
    | `admin.roles:read`         | System role assignments (full results also require Organization **Owner** authorization, see warning below) | Enterprise Grid only                 |
    | `auditlogs:read`           | Organization-wide audit activity (requires Organization **Owner** authorization, see warning below)         | Enterprise Grid only                 |

    <Note>
      The `admin.*` scopes can be granted by an Organization Owner or Admin, and only on an Enterprise Grid plan. On lower plans these scopes are unavailable, and Oleria limits discovery to accounts, channels, user groups, and resources.
    </Note>

    <Warning>
      Two of the Grid scopes above need a stricter grant than the rest: `auditlogs:read` and `admin.roles:read` both require authorization by an Organization **Owner**, not just an Admin. Slack's Audit Logs API does not accept Organization Admin tokens ("administrator tokens are not currently supported"), so an Admin-authorized install will complete every other org-discovery scope but fail audit log ingestion outright. `admin.roles:read` degrades more quietly under an Admin-authorized install - system role assignments return `missing_scope` or come back filtered rather than failing outright. If audit activity is missing or system roles look incomplete, confirm the app was installed by an Owner, not an Admin.
    </Warning>
  </Step>

  <Step title="Install the app">
    From **OAuth & Permissions** (or **Install App**), install the app and authorize the requested scopes:

    * For a **single workspace**, select **Install to Workspace**.
    * For **Enterprise Grid**, install the app to the **organization**. This may require Org Owner approval.
  </Step>

  <Step title="Copy your tokens">
    After installing, return to **OAuth & Permissions** and copy the tokens you will paste into Oleria:

    * **Bot User OAuth Token** - begins with `xoxb-`. Required for a single workspace. Optional for Enterprise Grid - channel and user group discovery normally read from the bot token, but automatically fall back to the user token if the bot token is omitted.
    * **User OAuth Token** - begins with `xoxp-`. Required for every connection - single workspace or Enterprise Grid.

    <Warning>
      Treat these tokens like passwords. Store them securely - anyone with a token can read the data the scopes allow. Oleria stores them encrypted and never displays them again after you save the integration.
    </Warning>
  </Step>

  <Step title="Find your Slack URL and IDs">
    Collect the remaining values you will need when connecting in Oleria:

    * **Slack URL** - your workspace URL, in the form `https://acme.slack.com`. For an Enterprise Grid organization use `https://acme.enterprise.slack.com`.
    * **Team ID** (single workspace) - the workspace ID, which starts with `T`. Open Slack in a browser and read it from the URL: `app.slack.com/client/T0XXXXXXXX/...`.
    * **Enterprise ID** (Enterprise Grid) - the organization ID, which starts with `E`. Find it in the [Slack admin console](https://admin.slack.com/) or the org's admin URL.
  </Step>
</Steps>

## Connect Slack to Oleria

<Steps>
  <Step title="Open the integration">
    Go to your Oleria workspace, select **Integrations** → select **Slack**.
  </Step>

  <Step title="Complete the connection form">
    Select **Continue** and fill in the connection form:

    | Field             | Notes                                                                                                                                                                                      |
    | :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Integration scope | Required. Choose **Single workspace** (default) or **Enterprise Grid (organization)**.                                                                                                     |
    | Slack URL         | Required. Your workspace URL (e.g. `https://acme.slack.com`), or your org URL (`https://acme.enterprise.slack.com`) for Enterprise Grid.                                                   |
    | Team ID           | Single workspace only. The workspace ID starting with `T` (e.g. `T0XXXXXXXX`).                                                                                                             |
    | Enterprise ID     | Enterprise Grid only. The organization ID starting with `E` (e.g. `E0XXXXXXXX`).                                                                                                           |
    | Bot Token         | The `xoxb-` token. Required for a single workspace. Optional for Enterprise Grid - channel and user group discovery normally read from it, falling back to the user token if it's omitted. |
    | User Token        | Required for every connection. The `xoxp-` token - `search:read` scope for full resource discovery on either scope, plus the `admin.*` scopes for Enterprise Grid.                         |

    Team ID and Enterprise ID toggle based on the integration scope you selected; Bot Token and User Token are always shown.
  </Step>

  <Step title="Save the integration">
    Select **Authenticate** to validate and save the integration. Oleria runs a quick check against Slack to confirm the tokens are valid before saving.
  </Step>
</Steps>

## Verify the integration

Confirm the Slack instance appears in your Oleria workspace connected integrations. After the first sync completes, you can review the discovered accounts, channels, resources, and user groups in your Oleria workspace.

<Note>
  On plans below Enterprise Grid, workspace, installed-app, system role, and audit data will not appear - this is expected. Connect at the organization level on an Enterprise Grid plan for full coverage.
</Note>

<Note>
  Resource (file) discovery also depends on the user token, independent of plan or scope. Without one, Oleria only sees files in channels the bot has been explicitly added to.
</Note>

<Note>
  Slack tokens are long-lived and do not expire by default. If you reinstall the app, rotate, or revoke its tokens, update the bot and user tokens in Oleria by editing the integration. Revoked tokens will cause discovery to stop.
</Note>

## Contact us

For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com).