# Slack: OAuth app setup and approval
Capped · Sourced · updated 27 Oct 2026 · https://oauth-guide.akshatsethi.com/apps/slack

> Any workspace can install your Slack app over OAuth on the same day: you create the app, complete the distribution checklist and turn on public distribution, with no review. The catch is that unlisted apps get severe rate limits on reading message history (conversations.history and conversations.replies drop to 1 request per minute). Lifting that limit means getting into the Slack Marketplace, which requires 10+ active installs and a review that can take up to about 12 weeks.

- **Your hands-on work:** 1–3 h
- **Waiting on Slack:** None
- **First user can connect:** Today, in about 30 minutes
- **Why Capped:** Public OAuth distribution needs no review, but unlisted (non-Marketplace) apps are limited to 1 request per minute and 15 objects per call on conversations.history and conversations.replies until they pass Marketplace review.
- **Using Composio?** Composio has a managed Slack OAuth app, so you can prototype before you register your own. Register your own app before launch so your name appears on the install screen. A shared app is also unlikely to give you Marketplace-level rate limits.

## Path to launch
### Build: Your workspace
- Who can connect: Only the workspace that owns the app (its development workspace).
- What users see: The standard Slack install/consent screen listing the requested bot and user scopes.
- Effort: 20–45 min · Wait: None
- Next: Complete the Manage Distribution checklist and click Activate Public Distribution.
- _(Docs [1, 2])_

### Beta: Unlisted public distribution
- Who can connect: Any Slack workspace, through your install URL or Add to Slack button. Admins in some workspaces must approve the app first.
- What users see: The standard consent screen. There is no Marketplace listing, and the workspace may show an admin-approval request.
- Effort: 30–90 min · Wait: None
- Next: Reach 10+ active workspace installs, then pass Slack Marketplace review. You only need this if you want the higher rate limits or a listing.
- _(Docs [2, 3, 4])_

### Launch: Slack Marketplace
- Who can connect: Any workspace. Users can also install directly from the Marketplace, and the normal rate limits apply.
- What users see: A Marketplace listing page plus the standard consent screen.
- Effort: 1–3 days · Wait: 2–12 weeks
- _(Docs [4, 5], medium confidence)_

## Before you start
- [ ] **A Slack workspace you can sign in to** (You). Apps are created under a Slack account and owned by a development workspace. _(Docs [1])_
- [ ] **An HTTPS redirect URI** (Agent). Redirect URLs must use HTTPS and can't contain '#'. Event and interaction URLs also need SSL. _(Docs [1, 2])_
- [ ] **A working OAuth v2 flow** (Agent). Distributed apps must use OAuth to get a token for each workspace and user. A single-workspace install doesn't need it. _(Docs [2])_
- [ ] **10+ active workspace installs** (You). Marketplace submission requires installs on at least 10 workspaces active in the past 28 days, and that count must hold for the whole review. _(Docs [4, 5])_
- [ ] **Demo video and reviewer test account** (You). You need a video showing install, OAuth, setup, use and uninstall. You also need test credentials with dummy data for your service. _(Docs [4])_

## Steps
1. **Create a Slack app** (You, 5–10 min). Sign in at api.slack.com/apps and create a new app, either from scratch or from a manifest. Pick the development workspace that will own it. _(Docs [1, 2])_
   - Click Create New App
   - Choose From scratch or From an app manifest
   - Enter an app name and select the development workspace
   - Agent: Once you're signed in, an agent can fill the form or paste a manifest.
   - Watch out: The development workspace owns the app. Pick one you'll keep long-term.
2. **Add your redirect URI and scopes** (Agent, 10–20 min). Under OAuth & Permissions, add your redirect URI (HTTPS) and the bot scopes and user scopes your integration needs. Request only what you use, because workspace admins may have to approve the app. _(Docs [1])_
   - Open OAuth & Permissions
   - Add your redirect URI under Redirect URLs and save
   - Add Bot Token Scopes and/or User Token Scopes
   - Agent: An agent can do all of this. It should not copy the client secret.
   - Watch out: If you configure several redirect URLs, send the same redirect_uri in the authorize call and in oauth.v2.access, or you'll get bad_redirect_uri.
3. **Put the client ID and secret into your OAuth client** (You, 5–10 min). Copy the Client ID and Client Secret from Basic Information > App Credentials into your OAuth client. Set the authorize URL to https://slack.com/oauth/v2/authorize and the token URL to https://slack.com/api/oauth.v2.access. _(Docs [1])_
   - Copy the Client ID
   - Copy the Client Secret into your secret store
   - Use the scope parameter for bot scopes and user_scope for user scopes
   - Agent: An agent can enter the client ID and the URLs. A person handles the client secret.
   - Watch out: User tokens come back under authed_user, not at the top level of the token response.
4. **Test an install on your own workspace** (Agent, 5–10 min). Run the OAuth flow against your development workspace and confirm that a token comes back. _(Docs [1])_
   - Agent: An agent can run the flow. A person may need to click Allow.
   - Watch out: Installing in any other workspace before you enable distribution fails with invalid_team_for_non_distributed_app.
5. **Activate public distribution** (You, 15–30 min). In Manage Distribution, complete every checklist item (for example, remove hard-coded tokens and use HTTPS), then click Activate Public Distribution. No review is involved. You get a shareable install URL and an Add to Slack button. _(Docs [2, 3])_
   - Open Manage Distribution
   - Complete each checklist item
   - Click Activate Public Distribution
   - Agent: An agent can work through the checklist. A person should confirm activation.
   - Watch out: Unlisted apps created after May 29, 2025 get conversations.history and conversations.replies at 1 request per minute and 15 objects per call. Plan around this if you read message history.
6. **Get 10+ active workspace installs** (You, Unknown). Marketplace submission requires at least 10 installs on workspaces active in the past 28 days. Test install, use and uninstall on a workspace other than your development one. _(Docs [4, 5])_
   - Watch out: If installs drop below 10 during review, the submission is affected.
7. **Submit to the Slack Marketplace** (You, 1–3 days). Fill in the listing, write a justification for each scope, provide reviewer test credentials, and record a demo video covering install, OAuth, setup, use and uninstall. Fix anything the automated tests flag before you submit. _(Docs [4])_
   - Fill in the listing info and support details
   - Justify every requested scope
   - Provide test account credentials with dummy data
   - Upload the demo video
   - Run the automated tests and submit
   - Agent: An agent can draft listing copy and scope justifications. A person records the video and submits.
   - Watch out: Legacy, restricted and broad data-access scopes aren't allowed. Failing preliminary review resets your place in the queue.
8. **Wait for preliminary and functional review** (Provider, wait 2–12 weeks). Preliminary review takes up to 10 business days. Functional review takes up to 10 weeks for new apps. Once approved, you choose when to publish. _(Docs [4, 6], medium confidence)_
   - Watch out: Reviews can't be expedited, so plan for several rounds of feedback.

## Scopes
Slack doesn't classify scopes for OAuth approval. Any scope works for unlisted distribution. Marketplace review checks each scope and rejects some.

| Scope | Grants | Level | Consequence |
|---|---|---|---|
| `Standard bot/user scopes (e.g. chat:write, channels:read)` | Normal app functions | basic | Nothing for unlisted apps. A scope justification during Marketplace review. |
| `channels:history / groups:history / im:history (conversations.history, conversations.replies)` | Reading message history | sensitive | Allowed, but unlisted apps are limited to 1 request per minute and 15 objects per call until Marketplace approval. |
| `Legacy, restricted or broad data-access scopes` | Wide workspace data access | restricted | Not allowed in the Marketplace. |

## When you get stuck
- **invalid_team_for_non_distributed_app when another workspace installs.** Public distribution hasn't been activated. Fix: Complete the Manage Distribution checklist and activate public distribution. _(Docs [1])_
- **bad_redirect_uri during token exchange.** The redirect_uri differs between the authorize call and oauth.v2.access, or doesn't match a configured Redirect URL. Fix: Send the same redirect_uri in both calls, and make sure it matches (or is a subdirectory of) a configured URL. _(Docs [1])_
- **ratelimited errors and 15-message pages on conversations.history/replies.** Unlisted commercial apps are limited to Tier 1 (1 request per minute) for these methods. Fix: Get listed in the Slack Marketplace, or design around the limit (for example, use the Events API to capture messages as they arrive). _(Docs [3, 7])_
- **unapproved_scope error.** A published app requested a scope that Slack hasn't approved for it. Fix: Request only approved scopes, or submit the new scopes for Marketplace review. _(Docs [1])_

## Not confirmed yet
- **Do the reduced rate limits now apply to existing installs of unlisted apps?** Slack's own pages conflict. Dates given include Sept 2, 2025 and March 3, 2026, and one page says existing installs are exempt. To resolve: Check the current rate-limits page and the 2025-05 terms FAQ on docs.slack.dev, or test against an existing install.
- **How long Marketplace reviews actually take in practice** I found only Slack's stated maximums, no developer reports. To resolve: Check the estimated time shown on your app's submission page.

## Sources
1. [Installing with OAuth](https://docs.slack.dev/authentication/installing-with-oauth) (Slack developer docs). Checked 27 Oct 2026
2. [Distributing your app](https://docs.slack.dev/distribution) (Slack developer docs). Checked 27 Oct 2026
3. [Rate limit changes for non-Marketplace apps](https://docs.slack.dev/changelog/2025/05/29/rate-limit-changes-for-non-marketplace-apps) (Slack developer docs). Checked 27 Oct 2026
4. [Slack Marketplace review guide](https://docs.slack.dev/slack-marketplace/slack-marketplace-review-guide) (Slack developer docs). Checked 27 Oct 2026
5. [Slack Marketplace install requirement](https://docs.slack.dev/changelog/2026/09/01/slack-marketplace-install-requirement) (Slack developer docs). Checked 27 Oct 2026
6. [App review guide](https://api.slack.com/directory/app-review-guide) (Slack API). Not yet checked
7. [Rate limits](https://docs.slack.dev/apis/web-api/rate-limits) (Slack developer docs). Not yet checked
8. [Composio managed auth toolkits](https://docs.composio.dev/toolkits/managed-auth.md) (Composio docs). Checked 27 Oct 2026

Wrong or out of date? POST https://oauth-guide.akshatsethi.com/api/reports with {"app": "slack", "step": 2, "message": "what you saw"} (step is optional), or call the report_problem MCP tool. The next research run checks it.
Followed it? Say how it went: POST https://oauth-guide.akshatsethi.com/api/reports with {"app": "slack", "outcome": "worked" | "waiting" | "stuck", "step": 3, "message": "what happened"}, or call the report_setup MCP tool.