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

# Slack Admin

> Connect Slack's Enterprise Grid admin tools to Serval so workflows can invite, deactivate, and remove users and manage channel membership across your entire Slack organization.

## About Slack Admin

Slack Admin (shown in Serval as **Slack Enterprise Admin**) is the org-administration companion to the regular [Slack integration](/sections/integrations/slack). It connects to your Slack Enterprise Grid organization as one of your org admins and runs every action with that person's own permissions, so workflows can invite, deactivate, and remove users, manage channel membership, and look up people and channels across the whole org. The regular Slack integration still handles messaging, channel creation, user and group sync, and ticket sync - flows that both message people and manage the org need both connections.

**Authentication:** OAuth, authorized by an Enterprise Grid org admin or org owner. Either one click via Serval's managed Slack Admin app, or bring your own Slack app (created from a manifest Serval provides) using its Client ID and Client Secret.

**Data sync:** None. Slack Admin runs no scheduled syncs or background ingestion - everything executes on demand inside workflow runs using the stored admin token. User and group sync run through the regular Slack integration.

## What the Slack Admin integration enables

| Capability                        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Admin API requests                | Call any method in Slack's Enterprise Grid admin family as the connected admin - list, invite, and remove users, search channels, list workspaces, and more. Failed calls surface Slack's full error response so workflows fail loudly.                                                                                                                                                                                                                                                  |
| SCIM API requests                 | Call Slack's SCIM provisioning API, which powers full account deactivation.                                                                                                                                                                                                                                                                                                                                                                                                              |
| Name and email lookups            | Find a channel by name (archived channels excluded) or a user by email address, so workflows can use human-friendly names instead of Slack IDs. No match raises an error, and an ambiguous channel-name match is rejected rather than guessed.                                                                                                                                                                                                                                           |
| User lifecycle helpers            | Invite a user to a workspace (with a starter channel), remove a user from a workspace, or deactivate their account entirely.                                                                                                                                                                                                                                                                                                                                                             |
| Channel membership helpers        | Add a user to a channel (channel by name or ID, user by email) or remove them - including private channels.                                                                                                                                                                                                                                                                                                                                                                              |
| Installable "Admin API" workflows | A ready-made bundle in the Slack workflow catalog ("Manage Slack using the Admin API for Enterprise Grid organizations"): "Get Channel (Admin API)", "Get User (Admin API)", "Deactivate User (Admin API)", "Invite User (Admin API)", "List Teams (Admin API)", "Remove User from Slack Channel (Admin API)", and "Remove User from Workspace (Admin API)". Read-only workflows install without an approval step; workflows that change things default to requiring installer approval. |

Anything defined in the [Slack Admin API](https://api.slack.com/methods) can be accessed through Serval.

## Get your credentials

There are two ways to connect. The managed app is the fastest; bring your own app when your organization requires apps it controls or wants to trim the requested scopes.

<Tabs>
  <Tab title="Serval's managed Slack app">
    There is nothing to create. You just need the right person to click the button: an Enterprise Grid org admin or org owner - ideally the **primary org owner**, who has the most permissions. The admin permissions are granted to the person who authorizes, and Serval stores that person's token.

    <Note>
      Slack only grants these admin permissions on Enterprise plans, to org admins and owners. The connection is keyed to your Slack Enterprise organization (with a fallback for older "Enterprise Select" orgs).
    </Note>

    <Note>
      In some environments (mostly self-hosted deployments) Serval's managed credentials are not configured. The "Use Serval's Slack App" option is hidden and connection attempts show "Slack Admin OAuth is not configured in this environment". Use the bring-your-own-app path instead - it works with your own credentials.
    </Note>
  </Tab>

  <Tab title="Bring your own Slack app">
    You create a Slack app inside your own Enterprise Grid org from a manifest Serval renders for you, then hand Serval that app's Client ID and Client Secret. The manifest already contains the correct redirect URL and scope lists, and is set up for organization-level installs. Manage your apps at [api.slack.com/apps](https://api.slack.com/apps).

    <Steps>
      <Step title="Copy the manifest from Serval">
        In the Serval connect modal, optionally adjust **App Name** and the **Bot Scopes** / **User Scopes** pickers, then click "Copy & Go to Slack". This copies the rendered manifest and opens [Slack's app creation page](https://api.slack.com/apps?new_app=1).
      </Step>

      <Step title="Create the app from the manifest">
        At Slack, create the app "From a manifest" and paste the copied JSON. Do not edit the redirect URL or scopes by hand - the manifest is generated to match exactly what Serval's connection flow expects.
      </Step>

      <Step title="Copy the app credentials">
        Open your new app at [api.slack.com/apps](https://api.slack.com/apps), go to **Basic Information > App Credentials**, and copy the **Client ID** and **Client Secret**.
      </Step>

      <Step title="Finish in Serval">
        Back in Serval, click "I have my credentials", paste the Client ID and Client Secret, and click Connect. Complete the Slack authorization as an org admin or owner - the admin permissions are granted to **you**, and Serval stores your user token.
      </Step>
    </Steps>

    <Note>
      No signing secret is needed. The admin app receives no webhooks - it has no event subscriptions, interactivity, or slash commands.
    </Note>

    <Warning>
      The scopes Serval requests must exactly match what your Slack app is configured with, or Slack blocks the install. If you trimmed scopes on the app (commonly the Slack Connect scopes under `conversations.connect`), mirror that change in the Bot Scopes / User Scopes pickers before connecting.
    </Warning>
  </Tab>
</Tabs>

## Connect in Serval

<Steps>
  <Step title="Open the Slack Enterprise Admin connect modal">
    Find **Slack Enterprise Admin** in Serval's available integrations and open the connect flow. When Serval's managed app is available you can simply choose "Use Serval's Slack App" and authorize in Slack as an org admin or owner - you are done. Otherwise choose "Use Your Own Slack App" and continue with the custom app form below.
  </Step>

  <Step title="Fill in the custom app form">
    * **App Name** (optional). Pre-filled with "Serval Admin"; placeholder "My Company IT", helper text "This appears in Slack when your app sends messages." Cleared and left blank, the manifest falls back to "Serval Admin" and your connection is named "\[Enterprise name] (Custom App)".
    * **Bot Scopes** (optional). Pre-filled with the 31 default bot scopes; placeholder "Search or add a Slack bot scope...". Changing the selection **replaces** the default set wholesale; use the "Reset to defaults" link to restore it. Invalid entries are rejected with: Invalid Slack bot scope "\[scope]". Use Slack scope names like channels:read or files:write.
    * **User Scopes** (optional). Pre-filled with the 19 default user scopes; placeholder "Search or add a Slack user scope...". An invalid entry shows the bot-flavored message on screen; the server reports: invalid Slack user scope "\[scope]"; use scope names like admin.users:read or mpim:write.
    * **Client ID** (required). Placeholder "1234567890.1234567890". The backend rejects a blank value with "slackClientId is required".
    * **Client Secret** (required). Password field, placeholder "Enter your client secret". The backend rejects a blank value with "clientSecret is required".

    The Connect button stays disabled until both Client ID and Client Secret are filled in.
  </Step>

  <Step title="Connect and authorize in Slack">
    Click Connect and complete the Slack authorization as an org admin or owner. Finish within 10 minutes - your credentials travel in a signed, time-limited handoff that expires after that. Serval then discards your Client Secret and stores your encrypted admin user token, along with the app's bot token for the Slack Connect invite endpoints. The connection appears as "\[Enterprise name] (\[App name])".
  </Step>
</Steps>

<Note>
  There is no separate edit-credentials form for this integration. To update credentials later, run the connect flow again with both Client ID and Client Secret. Serval never stores the Client Secret, so there is no stored value to leave in place.
</Note>

## Verifying the connection

Slack Admin ships **no health checks**. The health checks you may see under Slack belong to the regular Slack connection, not this one.

To confirm the connection works, install a read-only workflow from the "Admin API" bundle in the Slack workflow catalog and run it - "List Teams (Admin API)" is the simplest: it lists the workspaces in your org without changing anything. "Get Channel (Admin API)" and "Get User (Admin API)" are also safe, read-only checks.

<Tip>
  If the connection authorizes fine but admin workflows fail with Slack permission errors, the authorizing admin is usually missing org-level permissions such as "Manage public channels for a team" or "Manage private channels at the org level" (in Slack org settings under **People > Manage permissions**). Grant the missing permissions, or reconnect as the primary org owner.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="It runs as a person, not a bot">
    The connection's primary credential is the authorizing admin's own user token - the bot token from the install is stored too, but used only for the Slack Connect invite endpoints (`conversations.requestSharedInvite.*`), which require a bot-only scope. Every other workflow call assumes that person's permissions, so anything their Slack role cannot do surfaces as a permission error at runtime. If that admin changes roles or is deactivated, the connection breaks until someone reconnects. The token is long-lived with no refresh flow (token rotation is deliberately disabled in the app manifest).
  </Accordion>

  <Accordion title="Who must authorize, and on what plan">
    Slack only grants the admin permissions to Enterprise org admins and owners, and the connection is keyed to your Enterprise Grid organization (older "Enterprise Select" orgs fall back to the workspace). Connect as the primary org owner where possible - other org owners and admins may lack default permissions like "Manage public channels for a team" or "Manage private channels at the org level", which causes runtime permission errors.
  </Accordion>

  <Accordion title="Companion to, not replacement for, the regular Slack integration">
    This connection only covers Slack's admin methods, user methods, oversight methods, the SCIM API, the Slack Connect invite methods, and one channel-removal method. Messaging, channel creation, user and group sync, and ticket sync all live on the regular [Slack integration](/sections/integrations/slack) - flows that both message people and manage the org need both connections. The Admin API catalog workflows even ship inside the Slack integration's workflow catalog.
  </Accordion>

  <Accordion title="Scope mismatch blocks custom app installs">
    For bring-your-own apps, the authorization request must only ask for scopes your Slack app is actually configured with. The Bot Scopes / User Scopes pickers replace the default sets when changed, precisely so teams that trimmed scopes (commonly the Slack Connect scopes under `conversations.connect`) are not blocked at install. After editing scopes on the Slack app itself, mirror the change in the pickers before reconnecting.
  </Accordion>

  <Accordion title="Slack says the app needs approval from an admin">
    The org-level install goes through Slack's app-approval gate like any other app: if your organization requires admin approval for new apps, the authorization screen asks you to request approval instead of offering **Allow** - for the managed app and bring-your-own apps alike. On Enterprise Grid, approvals are handled at **admin.slack.com > Apps > Requests**. The org admin or owner authorizing this integration often holds app-management rights and can approve the app themselves; otherwise submit the request or have an app manager approve it. After approval, rerun the connect flow from Serval - the earlier attempt does not resume, and on the bring-your-own path you enter the Client ID and Client Secret again (the Client Secret is never stored) and finish within the 10-minute handoff window.
  </Accordion>

  <Accordion title="Remove is not deactivate">
    "Remove User from Workspace (Admin API)" uses Slack's `admin.users.remove` method and explicitly does **not** deactivate the account. "Deactivate User (Admin API)" goes through Slack's SCIM API and disables the account itself. Pick the right one for offboarding.
  </Accordion>

  <Accordion title="Removing someone from a channel uses a non-admin method">
    Slack exposes no admin-family method for kicking a user from a channel, so channel removal deliberately uses the standard `conversations.kick` method with the admin's user token. The default user scopes include the non-admin `channels:write` and `groups:write` scopes specifically so removal works in both public and private channels - keep them if you customize scopes.
  </Accordion>

  <Accordion title="No health checks ship for this integration">
    Health checks are matched by integration, and none exist for Slack Admin - the Slack health checks belong to the regular Slack connection. Verify with a read-only catalog workflow such as "List Teams (Admin API)" instead.
  </Accordion>

  <Accordion title="Managed OAuth can be unavailable in some environments">
    If Serval's Slack Admin credentials are not configured in your environment (relevant mostly to self-hosted deployments), the managed connect path is unavailable and shows "Slack Admin OAuth is not configured in this environment". The bring-your-own-app path still works since it uses your credentials.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Slack Admin integration.