# Connect Slack

Canonical URL: https://docs.fuse.init.inc/integrations/slack/setup

Configure a Slack app OAuth client and create a verified Init connection.



## Before you start [#before-you-start]

**Engine operator** creates and configures one Slack app used by the Init platform. **Connection admin/user** installs that app into their Slack workspace during Connect.

You need:

* A Slack workspace where you can create or manage apps (or access to api.slack.com with create permission).
* A Slack admin or member who can approve app installation for the customer workspace.
* The engine public base URL for the OAuth redirect URL.

## Configure the provider [#configure-the-provider]

### One-time platform Slack app (**Engine operator**) [#one-time-platform-slack-app-engine-operator]

1. Create a Slack app at [api.slack.com/apps](https://api.slack.com/apps).

2. Under **OAuth & Permissions**, set the Redirect URL to:

   `{FUSE_PUBLIC_URL}/v1/oauth/slack/callback`

3. Add only the bot token scopes required by the Init actions you expose. Do not request unused scopes.

4. Install the app to a development workspace only for operator smoke tests; customer installs happen through Connect.

5. Copy the Client ID, Client Secret, and Signing Secret into the Fuse environment as `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET`, and `SLACK_SIGNING_SECRET`. Never commit these values.

### Per-workspace install (**Connection admin/user**) [#per-workspace-install-connection-adminuser]

Customers do not paste tokens. They authorize the platform Slack app into their workspace through Init Connect.

## Connect to Init [#connect-to-init]

1. **Connection admin/user** starts a Slack Connect session.
2. Slack prompts to select a workspace and approve the requested bot scopes.
3. Init completes the OAuth callback and stores the workspace connection. No customer credential fields are submitted.

If Init later requests additional bot scopes for new actions, reconnect and reinstall/reauthorize so Slack grants the updated scope set.

## Permissions [#permissions]

Bot token scopes are defined by the generated action scope matrix. Grant only those scopes on the Slack app and during install.

Workspace owners or admins may need to approve installation depending on workspace app-management settings. User token scopes are not used for this Init pack unless your deployment explicitly adds them.

## Verify the connection [#verify-the-connection]

1. Confirm Connect returns successfully and the Init connection is active for the expected Slack team.
2. Run a safe read-only probe such as listing conversations the bot can see, or Init’s connection test if available.
3. Success looks like a stored Slack authorization for the correct workspace and a read API call that does not return `invalid_auth` or `missing_scope`.

## Rotate or revoke access [#rotate-or-revoke-access]

* **Rotate platform secrets (Engine operator):** regenerate the Client Secret or Signing Secret in the Slack app settings, update `SLACK_CLIENT_SECRET` / `SLACK_SIGNING_SECRET`, then invalidate the previous values.
* **Revoke workspace access (Connection admin/user):** remove the app from the Slack workspace (Manage apps) or revoke the Init connection, then reconnect if needed.
* After scope changes on the Slack app, every customer workspace must reauthorize for the new scopes to take effect.

## Troubleshooting [#troubleshooting]

| Symptom                             | What to check                                                                                                   |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Redirect URL error                  | Exact match to `{FUSE_PUBLIC_URL}/v1/oauth/slack/callback`.                                                     |
| `missing_scope` on actions          | App scopes and the installed grant must include the scopes for those actions; reconnect after expanding scopes. |
| Install blocked by workspace policy | Ask a Slack workspace admin to approve the app.                                                                 |
| Wrong workspace connected           | Re-run Connect and select the intended workspace at Slack’s install prompt.                                     |
| Fuse cannot start OAuth             | Confirm `SLACK_CLIENT_ID` and `SLACK_CLIENT_SECRET` are configured on Fuse.                                     |