> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleria.com/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, 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, 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.
* **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) 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.
</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.
* 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, and user group 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                                                              |
| **Enterprise Grid (organization)** | A Grid organization spanning multiple workspaces, with admin and audit depth. | User token (with `admin.*` scopes); bot token optional but recommended |

## 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 |
  </Step>

  <Step title="Add user token scopes (Enterprise Grid only)">
    Skip this step for a single-workspace integration.

    For an Enterprise Grid organization, under **OAuth & Permissions** → **Scopes** → **User Token Scopes**, add the following. These enable admin and audit discovery across the organization:

    | Scope                      | Used for                                        |
    | :------------------------- | :---------------------------------------------- |
    | `admin.users:read`         | Enumerating accounts across the organization    |
    | `admin.teams:read`         | Discovering the workspaces in the organization  |
    | `admin.conversations:read` | Discovering channels, including shared channels |
    | `admin.apps:read`          | Installed-app inventory                         |
    | `admin.roles:read`         | System role assignments                         |
    | `auditlogs:read`           | Organization-wide audit activity                |

    <Note>
      The `admin.*` and `auditlogs:read` scopes can only 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, and user groups.
    </Note>
  </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 but recommended for Enterprise Grid (used for faster read calls).
    * **User OAuth Token** - begins with `xoxp-`. Required for Enterprise Grid organizations.

    <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; recommended for Enterprise Grid (used for faster read calls).                        |
    | User Token        | Enterprise Grid only. The `xoxp-` token with the `admin.*` scopes.                                                                       |

    The form shows only the fields that apply to the integration scope you selected.
  </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, 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>
  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).