# Add an OAuth Install Flow to a Slack Bolt App

Yes. An agent replaces your Bolt app's single bot token with the OAuth install flow, adds an installation store and the manifest's redirect URL, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-oauth-install-flow/slack-bolt/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the app authenticates today before it changes a line, because the OAuth flow replaces the token rather than sitting beside it. In an app laid out like slack-samples/bolt-js-getting-started-app, `package.json` is an ES module with one dependency, `@slack/bolt` at `^5.1.0` (the lockfile resolves 5.1.0), and one script, `start`, which is `node app.js`. `app.js` creates `new App({ token: process.env.SLACK_BOT_TOKEN, socketMode: true, appToken: process.env.SLACK_APP_TOKEN })`, listens for messages containing `hello` with a button block, acknowledges the `button_click` action, and starts on `process.env.PORT || 3000`. `manifest.json` asks for three bot scopes, `channels:history`, `chat:write` and `im:history`, subscribes to `message.channels` and `message.im`, enables interactivity and Socket Mode, sets `org_deploy_enabled` to true and `token_rotation_enabled` to false, and has an `oauth_config` with scopes but no `redirect_urls`. `AGENTS.md` says the code carries no comments and explains itself through names. The README's setup installs the app into one workspace by hand and exports the two tokens, which is exactly what a second workspace cannot do.

The agent keeps Socket Mode and adds OAuth on top of it, since Bolt's Socket Mode receiver serves the install and redirect routes over a small HTTP server on the port `app.start` already takes. `app.js` loses the `token` option and gains `clientId`, `clientSecret`, `stateSecret` and `signingSecret` from new environment variables, `scopes` copied from the manifest's three bot scopes so the two cannot disagree, and an `installationStore` with the three functions Bolt calls: `storeInstallation` keyed by `enterprise.id` for an org-wide install and `team.id` otherwise, `fetchInstallation` for the same keys, and `deleteInstallation` for the `app_uninstalled` and `tokens_revoked` events, which the agent subscribes to in the manifest so a workspace that removes the app is forgotten. `installerOptions.directInstall` is set so `/slack/install` sends a visitor straight to Slack's consent page. The store itself lives in `installation-store.js` as a JSON file keyed by those ids, with the file path from an environment variable, and its three functions are the whole interface a database-backed store would replace.

`manifest.json` gains `oauth_config.redirect_urls` with the app's public `https` address plus `/slack/oauth_redirect`, and `settings.event_subscriptions.bot_events` gains `app_uninstalled` and `tokens_revoked`. The README's setup section changes from exporting a bot token to reading the client id, client secret and signing secret from the app's Basic Information page, generating a state secret, and opening `/slack/install` once per workspace. Following `AGENTS.md`, the new code has no comments, and the reason for each change sits in the pull request description instead. `org_deploy_enabled` stays true, and the store's enterprise key is what makes an org-wide install resolve.

To check it, the agent runs `npm ci` and `node --check app.js` in its sandbox, writes `installation-store.test.js` with `node --test` covering store, fetch and delete for a team install and an enterprise install, and runs it. It then starts the app with placeholder secrets and no app token, which keeps Socket Mode from connecting, and requests `http://localhost:3000/slack/install` to confirm the receiver answers with a redirect to Slack's authorize URL carrying the three scopes and a state parameter, which it records. It does not install the app anywhere, because that needs your Slack app's credentials and a person's consent.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add Slack's OAuth install flow to this Bolt app so it can be installed in more than one workspace. Read package.json, app.js, manifest.json, AGENTS.md and README.md first. Keep Socket Mode. Replace the bot token with clientId, clientSecret, stateSecret and signingSecret from environment variables, set scopes from the manifest's bot scopes, and add an installationStore in its own module backed by a JSON file at a path from an environment variable, keyed by enterprise id for org installs and team id otherwise, with store, fetch and delete. Handle app_uninstalled and tokens_revoked by deleting the installation and subscribe to both in the manifest. Add the redirect URL to the manifest's oauth_config and update the README's setup steps. Follow AGENTS.md: no code comments. Add node --test tests for the store, run them, run node --check, start the app with placeholder secrets and show that /slack/install redirects to Slack's authorize URL with the scopes and a state parameter, and open a pull request with the output. Do not install the app anywhere.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request changes `app.js`, `manifest.json`, `README.md` and `package.json`, and adds `installation-store.js` and `installation-store.test.js`. Its description explains each change the way `AGENTS.md` asks, pastes the `node --test` output, and shows the redirect the install route returned in the sandbox with its scopes and state parameter.

The repository's only workflow handles Dependabot merges, so there is no check to wait for; the evidence is the run's record, with the test output, the `node --check` result and the HTTP exchange against the install route. The first real install happens when you open `/slack/install` with your own app's credentials.

Before merging, a reviewer decides whether the JSON store is enough for the first deployment or whether to swap the three functions for a database table now, whether to turn on token rotation in the manifest and in Bolt, and which public address goes into `redirect_urls`. The message and action listeners are unchanged.

## Run it on every Bolt app that still runs on one bot token

A team with several Slack apps sends this body once per repository to `POST /o/{org}/sessions`, each with its own repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own `app.js`: an app on an HTTP receiver gets the routes on that receiver instead of the Socket Mode server, and one that already uses an `authorize` function gets it replaced by the store rather than duplicated.

A `webhook_url` on the key reports each `run.completed` with the pull request in `result`, and a `run.failed` names an app whose code the agent could not start in its sandbox, for instance one that reads a secret at import time and exits without it.

## Why run it on Rush?

Moving a Bolt app from one token to OAuth touches the constructor, the manifest, the setup docs and two events, and the mistakes are quiet ones: a scope list that drifts from the manifest, an install keyed by team id that breaks for an org-wide install, an uninstall that leaves a dead token behind. The agent reads the manifest and the constructor together, keys the store the way Bolt will look it up, and proves the install route answers in its own sandbox.

The tests, the start-up log and the install redirect stay with the run and are pasted into the pull request, so the review is reading evidence rather than re-deriving Bolt's OAuth options. Several apps can get the same change at once, each in its own sandbox.

## Frequently asked questions

### Does the app have to leave Socket Mode?

No. Bolt's Socket Mode receiver can serve the `/slack/install` and `/slack/oauth_redirect` routes from a small HTTP server on the port the app already starts on, so events keep arriving over the socket and only the install pages are served over HTTP. The redirect URL in the manifest must point at that server's public `https` address.

### Where are the installations stored?

In a JSON file at a path from an environment variable, through a module that exposes exactly the three functions Bolt calls. That is enough to run and to test; the pull request names it as the module to replace with a database table before the app is installed widely, and the keys, enterprise id or team id, stay the same.

### Will it still work for the workspace that installed it by hand?

Not with the old token, because the `token` option is removed. That workspace installs once more through `/slack/install`, which takes a few seconds, and from then on its token lives in the store like every other workspace's.

### Does the agent install the app into a workspace to test?

No. Installing needs your app's client secret and a person's consent on Slack's page, so the agent stops at proving the install route redirects to Slack's authorize URL with the right scopes and a state parameter, and at testing the store. The first install is yours.

## More Slack Bolt jobs

- [Add Scheduled Messages to a Slack Bolt App](https://getrush.ai/run/add-scheduled-messages/slack-bolt/)
- [Add a Slash Command With a Modal to a Slack Bolt App](https://getrush.ai/run/add-slash-command/slack-bolt/)
- [Add Structured Logging to a Slack Bolt App](https://getrush.ai/run/add-structured-logging/slack-bolt/)

## More jobs like this: Hand off a long task

- [Publish Manifests as OCI Artifacts for Flux](https://getrush.ai/run/add-oci-artifacts/flux/)
- [Set Up SQLx Offline Mode So a Rust App Builds Without a Database](https://getrush.ai/run/add-offline-mode/sqlx/)
- [Add an SQLx Offline Query Check to CI](https://getrush.ai/run/add-offline-query-check-to-ci/sqlx/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
