Slack
The Slack integration monitors your workspace's members and guest accounts, bot users, installed applications, user groups, IDP-synced groups, and channel access — including externally shared channels. It can also execute remediation actions (deactivate users, remove channel/user-group access, reset sessions) when the corresponding admin token is configured — see Remediation actions.
Before starting
You will need:
- Admin access to your Slack workspace (to create and install a Slack app).
- For the optional app-inventory and remediation tier: a workspace admin (a Workspace Owner, if you want user deactivation) willing to grant a user token.
- For the optional Enterprise Grid tier: org owner access to install an org-level app.
1. Create a Slack app
- Go to api.slack.com/apps and click Create New App → From scratch.
- Name it (e.g.
SlashID Sync) and select your workspace.
2. Grant bot token scopes
Under OAuth & Permissions → Scopes → Bot Token Scopes, add:
| Scope | Used for |
|---|---|
users:read | Members, guests, and bot users |
users:read.email | Email addresses (identity matching) |
usergroups:read | User groups and their members |
team:read | Workspace metadata |
channels:read | Public channels and membership |
groups:read | Private channels the bot is invited to |
3. Install the app and copy the bot token
- Under OAuth & Permissions, click Install to Workspace and authorize.
- Copy the Bot User OAuth Token (
xoxb-...).
The bot only sees private channels it has been invited to. Invite it to private channels you want covered, or use the Enterprise Grid tier for full visibility.
4. (Optional) Admin user token for app inventory and remediations
The admin user token unlocks two capabilities on non-Grid plans:
- App inventory: without Enterprise Grid, Slack has no API that lists all installed
apps. SlashID reconstructs the installed-app inventory from the workspace's
integration activity log, which requires the legacy
adminscope. - Remediation actions: deactivating users and removing channel or user-group access are admin operations that the bot token cannot perform.
To create it:
Open your Slack app at api.slack.com/apps (the same app from step 1 works — you don't need a second one).
Under OAuth & Permissions → Scopes → User Token Scopes (not Bot Token Scopes), add:
Scope Used for adminIntegration activity log (app inventory) and SCIM deactivation channels:writeRemoving users from public channels groups:writeRemoving users from private channels usergroups:readReading user-group membership before an update usergroups:writeRemoving users from user groups Have a workspace admin install (or reinstall) the app and authorize it while signed in as themselves. The token inherits the installing user's privileges, so:
- a Workspace Admin or Owner is required for the
adminscope to work; - a Workspace Owner on a Business+ plan is required for SCIM user deactivation.
- a Workspace Admin or Owner is required for the
Under OAuth & Permissions, copy the User OAuth Token (
xoxp-...) — it is shown alongside the bot token from step 3.
This is a personal, high-privilege credential: it acts as that admin and stops working if they are deactivated or lose admin rights. Prefer the Enterprise Grid tier when available. Without either optional token, SlashID still discovers apps through their bot users — most modern apps — just not apps installed with user tokens only, and remediation actions will fail with an error asking for an admin token.
5. (Optional) Enterprise Grid org admin token
On Enterprise Grid, install the app on the organization (not a single workspace) — under User Token Scopes, add:
| Scope | Used for |
|---|---|
admin.teams:read | Enumerating all workspaces in the org |
admin.users:read | Org-wide users and per-workspace membership |
admin.apps:read | The authoritative installed/restricted app inventory |
admin.conversations:read | The org-wide channel inventory, including private channels the bot never joined |
admin | SCIM reads: the IDP group inventory and identity-provider external IDs |
admin.users:write | Remediations: removing users from a workspace and resetting sessions |
channels:write | Remediations: removing users from public channels |
groups:write | Remediations: removing users from private channels |
usergroups:read | Remediations: reading user-group membership before an update |
usergroups:write | Remediations: removing users from user groups |
admin.conversations:read and the legacy admin scope are easy to miss, and omitting
them fails quietly: the token authenticates, passes every other health check, and the
org-wide channel inventory and IDP groups simply come back empty.
This unlocks:
- The authoritative installed/restricted app inventory with granted scopes
- All workspaces in the org and per-workspace membership
- All channels org-wide (including private channels)
- IDP groups via the SCIM API
- All remediation actions, including the two Grid-only ones (workspace removal and session reset)
6. Create your Slack↔SlashID Integration
Go to the SlashID Console integrations page and create a Slack connection:
| SlashID Console field | Description | Example |
|---|---|---|
| Name of the connection | Arbitrary name for this connection | Slack Production |
| Authoritative status | Whether Slack identities are the primary source of truth when reconciling identities across providers | Primary or Secondary |
| Workspace URL | Your Slack workspace URL | https://yourcompany.slack.com |
| Bot token | The bot token from step 3 | xoxb-... |
| Admin user token | (Optional) The admin user token from step 4 | xoxp-... |
| Org admin token | (Optional) The Enterprise Grid org-level token from step 5 | xoxp-... |
The Bot token field is the only one that takes a xoxb-... token — Admin user
token and Org admin token both take a xoxp-... token instead. Pasting the
xoxp-... User OAuth Token into the Bot token field is a common mix-up; see
Troubleshooting if the health check rejects the bot token.
What SlashID syncs
After the connection is created, SlashID periodically syncs:
- Always (bot token): members and guests, bot users, user groups, workspace metadata, channels with membership, and apps discovered via their bot users.
- With the admin user token: the full reconstructed app install inventory.
- With the org admin token: all workspaces, org-wide users, the authoritative app inventory with scopes, all channels, and IDP groups.
The health check surfaces this as an advisory, not a failure: if neither optional token is configured, it flags that the app inventory is limited to bot-user-derived apps and that remediation actions are unavailable; on Enterprise Grid, it separately flags a missing org admin token.
Remediation actions and required scopes
Remediations never use the bot token. Each action uses the org admin token when configured, falling back to the admin user token — except the two Grid-only actions, which require the org admin token. An action requested without a suitable token fails with an error naming the missing token; it is never silently skipped.
| Action | Slack API | Token | Required scope |
|---|---|---|---|
| Suspend / disable user | SCIM PATCH /Users (active: false) | Org admin token or admin user token | admin (token from a Workspace Owner; Business+ or Grid plan) |
| Remove user from channel | conversations.kick | Org admin token or admin user token | channels:write (public), groups:write (private) |
| Remove user from user group | usergroups.users.list + usergroups.users.update | Org admin token or admin user token | usergroups:read, usergroups:write |
| Delete user (remove from workspace) | admin.users.remove | Org admin token only (Grid) | admin.users:write |
| Reset user sessions | admin.users.session.reset | Org admin token only (Grid) | admin.users:write |
SCIM user deactivation requires a Business+ or Enterprise Grid plan — on Free and Pro plans Slack does not expose the SCIM API, so the suspend/disable action is unavailable. Removing a user from a user group fails if they are its last member, because Slack rejects empty user groups.
Troubleshooting
| Error / symptom | Cause | Fix |
|---|---|---|
invalid_auth | Token revoked, wrong token, or app uninstalled | Reinstall the app and update the token in the SlashID Console |
missing_scope | A required scope was not granted | The error names the missing scope — add it under Bot Token Scopes and reinstall the app |
not_allowed_token_type | The token is valid but of the wrong class for this API method — granting scopes will not fix it. Most often the app-level token (xapp-..., from Basic Information) was pasted into the bot token field; a user token (xoxp-...) produces the same error | Use the Bot User OAuth Token (xoxb-...) from OAuth & Permissions as the bot token |
| Health check "Verify credentials" fails: bot token is wrong class | A xoxp-... User OAuth Token was entered in the Bot token field | Use the Bot User OAuth Token (xoxb-...); xoxp-... belongs in Admin user or Org admin token |
| Empty or partial app list | No optional token configured | Expected: only bot-user-derived apps appear. Add an optional token for fuller coverage |
SCIM 403 | Org token lacks SCIM provisioning access, or the plan is not Enterprise Grid | Verify Grid plan and that the org-level app install includes provisioning access |
| Private channels missing | Bot not invited and no org admin token | Invite the bot to the channels, or configure the Enterprise Grid tier |
| Remediation fails: "requires an admin user token" | Neither optional token is configured | Create the admin user token (step 4) or org admin token (step 5) and add it to the connection |
| Remediation fails: "requires the Enterprise Grid org admin token" | Workspace removal / session reset attempted without an org token | These two actions are Grid-only — configure the org admin token (step 5) |
Suspend/disable fails with SCIM 401/403 | Token lacks the admin scope, installer is not a Workspace Owner, or plan is below Business+ | Reinstall the app as a Workspace Owner with the admin user scope on a Business+ or Grid plan |