Slack

• BlockerHistory and replies throttled to 1 call/min with 15 messages for non-Marketplace appswhy & fix →
• WarningCustomer-built 'custom app' workaround violates the Termswhy & fix →
• WarningMarketplace chicken-and-egg: 10 active workspaces before you can submitwhy & fix →
• Warning`*:history` scopes trigger enhanced review and AI ruleswhy & fix →
• WarningApp uninstalls itself when the installer leaveswhy & fix →
• WarningToken rotation and PKCE are one-way switcheswhy & fix →
• InfoEnterprise org installs land in zero workspaceswhy & fix →
• InfoMultiple redirect URLs require redirect_uri on both legswhy & fix →

• ☐A development Slack workspace◆Source-backedStated in official provider documentation we cite, but not observed by us.[S2] Slack Docs: Distributing your app (unlisted vs Marketplace, reinstall rules)why →
• ☐Public HTTPS endpoints◆Source-backedStated in official provider documentation we cite, but not observed by us.[S2] Slack Docs: Distributing your app (unlisted vs Marketplace, reinstall rules)[S1] Slack Docs: Installing with OAuthwhy →
• ☐Distribution strategy decisionbusiness / legal◆Source-backedStated in official provider documentation we cite, but not observed by us.[S2] Slack Docs: Distributing your app (unlisted vs Marketplace, reinstall rules)[S3] Slack Changelog (2025-05-29): Rate limit changes for non-Marketplace appswhy →
• ☐Landing, support and privacy pages, plus AI disclosures (for the Marketplace)business / legal◆Source-backedStated in official provider documentation we cite, but not observed by us.[S10] Slack Docs: Slack Marketplace app guidelines and requirementswhy →
• ☐Customer workspace or org admincustomer's admin◆Source-backedStated in official provider documentation we cite, but not observed by us.[S2] Slack Docs: Distributing your app (unlisted vs Marketplace, reinstall rules)[S11] Slack Docs: Developing for Enterprise orgswhy →

Developer console

https://api.slack.com/appsCopy

OAuth docs

https://docs.slack.dev/authentication/installing-with-oauthCopy

Authorize URL

https://slack.com/oauth/v2/authorizeCopy

Token URL

https://slack.com/api/oauth.v2.accessCopy

Discovery

https://slack.com/.well-known/openid-configurationCopy

You are building a Slack AI agent bot that reads channel messages and posts replies in customers' workspaces.

Context: the human has created a Slack app from slack-manifest.yaml (in the repo) and put SLACK_CLIENT_ID, SLACK_CLIENT_SECRET and SLACK_SIGNING_SECRET in the environment.

Implement with Bolt for JavaScript (or Python):
1. OAuth install flow: /slack/install redirects to https://slack.com/oauth/v2/authorize with scope=app_mentions:read,chat:write,channels:history,groups:history,im:history,channels:read,users:read, a random state and an explicit redirect_uri. /slack/oauth_redirect verifies state and calls oauth.v2.access with the SAME redirect_uri. Store installations keyed by enterprise_id when is_enterprise_install is true, otherwise by team.id. Check `ok` on every Slack response, because errors come back as HTTP 200.
2. Event handling: subscribe to app_mention, message.channels, message.groups and message.im. Verify request signatures and ack within 3 seconds. Maintain a rolling per-channel and per-thread context cache from incoming events, since there are no historical backfills by default.
3. History budget: wrap conversations.history and conversations.replies in a per-workspace limiter of 1 call per 60 seconds with limit<=15, because the app is distributed outside the Slack Marketplace. Honour Retry-After on `ratelimited`. Make the limiter configurable so it can be raised to Tier 3 once Marketplace approval lands.
4. Replies: chat.postMessage with thread_ts, at most about 1 message/sec per channel.
5. Lifecycle: handle app_uninstalled and tokens_revoked by deleting tokens and notifying our backend. Enterprise installs: after OAuth, redirect to https://app.slack.com/manage/{ENTERPRISE_ID}/integrations/profile/{APP_ID}/workspaces/add and pass team_id on API calls.
6. Do NOT enable token rotation or PKCE in the manifest unless refresh handling is implemented and tested, because both are irreversible. Do not use Slack data for model training, and do not auto-join channels.
7. Tests: state mismatch, bad_redirect_uri, enterprise install payload, the limiter under burst, uninstall event.

If an app configuration token is provided (SLACK_CONFIG_TOKEN, which expires after 12h), sync slack-manifest.yaml to the app with apps.manifest.update and report whether permissions_updated is true (that means existing workspaces must reinstall).

_metadata:
  major_version: 2
  minor_version: 1
display_information:
  name: Acme Agent
  description: An AI assistant that answers questions in your channels.
  long_description: Acme Agent answers questions when you mention it in a channel or send it a direct message. It reads only the channels it is invited to and replies in threads. Acme does not use Slack data to train AI models. Responses are generated by an AI model and may be inaccurate, so verify important information before acting on it.
  background_color: "#1f2937"
features:
  bot_user:
    display_name: Acme Agent
    always_online: true
oauth_config:
  redirect_urls:
    - https://app.example.com/slack/oauth_redirect
    - https://staging.example.com/slack/oauth_redirect
  scopes:
    bot:
      - app_mentions:read
      - chat:write
      - channels:history
      - groups:history
      - im:history
      - channels:read
      - users:read
  # pkce_enabled: true            # irreversible once enabled
settings:
  event_subscriptions:
    request_url: https://app.example.com/slack/events
    bot_events:
      - app_mention
      - message.channels
      - message.groups
      - message.im
  interactivity:
    is_enabled: false
  org_deploy_enabled: false       # true for Enterprise org-ready apps (requires reinstall)
  socket_mode_enabled: false
  token_rotation_enabled: false   # irreversible once enabled

# Slack app credentials (api.slack.com/apps > Basic Information)
SLACK_CLIENT_ID=1234567890.1234567890123
SLACK_CLIENT_SECRET=replace-with-client-secret
SLACK_SIGNING_SECRET=replace-with-signing-secret
SLACK_STATE_SECRET=replace-with-random-string
SLACK_REDIRECT_URI=https://app.example.com/slack/oauth_redirect
SLACK_BOT_SCOPES=app_mentions:read,chat:write,channels:history,groups:history,im:history,channels:read,users:read
# Non-Marketplace distributed apps: 1 call/min, limit<=15 on conversations.history/replies
SLACK_HISTORY_CALLS_PER_MIN=1
SLACK_HISTORY_PAGE_LIMIT=15
# Optional, for apps.manifest.update (expires after 12h; rotate with tooling.tokens.rotate)
SLACK_CONFIG_TOKEN=xoxe.xoxp-replace-me
SLACK_CONFIG_REFRESH_TOKEN=xoxe-replace-me

Getting a bot token in your own workspace takes minutes, and you can distribute to other workspaces the same day without review. But since 29 May 2025, a commercially distributed app that isn't approved for the Slack Marketplace is throttled to 1 request/minute and 15 messages per call on conversations.history and conversations.replies, so an AI agent that reads channel context effectively needs Marketplace approval. That approval requires 10+ active workspaces before you can submit, an enhanced review for `*:history` scopes, and up to about 12 weeks of review.

Apps are created instantly, from a manifest or the UI, and work in your own workspace. Clicking 'Activate Public Distribution' lets any workspace install the app with no review. Slack's API Terms (updated May 2025) say the Marketplace is the only appropriate channel for commercial distribution, and unlisted apps get crippled history and replies rate limits. A reading agent therefore needs review to scale.

Rating: Audits, partner approval or multi-week reviews that you can't speed up.

What affects your setup

• Manual app review◆Source-backed· S9 S10Source-backedStated in official provider documentation we cite, but not observed by us.[S9] Slack Docs: Slack Marketplace review guide[S10] Slack Docs: Slack Marketplace app guidelines and requirements

  Slack Marketplace review has two stages. The preliminary review gives feedback in up to 10 business days. The functional review takes up to 10 weeks for new submissions and 6 weeks for updates. Requesting `*:history`, `search:read.*`, `files:read` or `canvases:read` triggers an 'enhanced review'. Submission is blocked until the app is installed on 10 or more active workspaces (used in the past 28 days, not sandboxes).

• Marketplace listing optional◆Source-backed· S3 S2 S13Source-backedStated in official provider documentation we cite, but not observed by us.[S3] Slack Changelog (2025-05-29): Rate limit changes for non-Marketplace apps[S2] Slack Docs: Distributing your app (unlisted vs Marketplace, reinstall rules)[S13] Slack Docs: Real-time Search API

  Optional only on paper. Unlisted distribution works without review, but the API Terms call the Marketplace the only appropriate channel for commercially distributing apps. Non-Marketplace commercial apps get Tier 1 limits on conversations.history and conversations.replies (1 request/min, max 15 objects). The Real-time Search API is available only to Marketplace-published and internal apps.

• Customer admin consent◆Source-backed· S2 S11 S12Source-backedStated in official provider documentation we cite, but not observed by us.[S2] Slack Docs: Distributing your app (unlisted vs Marketplace, reinstall rules)[S11] Slack Docs: Developing for Enterprise orgs[S12] Slack Docs: Managing app approvals

  Workspaces can restrict installs to admins, require admin approval of app requests, or allow only Marketplace-listed apps. In Enterprise orgs, an Org Admin installs an org-ready app at org level and then must separately add it to individual workspaces.

• Policy URLs required◆Source-backed· S10Source-backedStated in official provider documentation we cite, but not observed by us.[S10] Slack Docs: Slack Marketplace app guidelines and requirements

  Marketplace listing requires a landing page, a support page and a privacy policy that explains how Slack data is handled. AI apps must also disclose the model used, data retention, LLM data tenancy and residency, and show an inaccuracy disclaimer. Plain unlisted distribution has no policy-URL requirement in the docs we read.

• Redirect URI rules◆Source-backed· S1 S2 S7Source-backedStated in official provider documentation we cite, but not observed by us.[S1] Slack Docs: Installing with OAuth[S2] Slack Docs: Distributing your app (unlisted vs Marketplace, reinstall rules)[S7] Slack Docs: App manifest reference

  Redirect URLs must use HTTPS. The redirect_uri you send must match, or be a subdirectory of, a configured Redirect URL, and anchors (#) are not allowed. With multiple Redirect URLs configured, you must send the same redirect_uri to both authorize and oauth.v2.access, or you get bad_redirect_uri. Up to 1,000 redirect URLs are allowed in the manifest. Distributed apps must use SSL for Events API, interactivity and slash-command URLs too.

• Token lifecycle gotchas◆Source-backed· S1 S6 S2Source-backedStated in official provider documentation we cite, but not observed by us.[S1] Slack Docs: Installing with OAuth[S6] Slack Docs: Using token rotation[S2] Slack Docs: Distributing your app (unlisted vs Marketplace, reinstall rules)

  Bot and user tokens never expire by default. Token rotation (12-hour xoxe tokens plus single-use refresh tokens) is optional but cannot be turned off once enabled, and the manifest's pkce_enabled and token_management_enabled settings are also irreversible. Apps that use scopes beyond bot, incoming-webhook, commands and identify are automatically uninstalled when the installing user leaves the workspace or becomes a guest.

Before you start — why each matters

• A development Slack workspace — Every app is created in one associated workspace. You need permission to install apps there; a developer sandbox works. ◆Source-backed· S2Source-backedStated in official provider documentation we cite, but not observed by us.[S2] Slack Docs: Distributing your app (unlisted vs Marketplace, reinstall rules)
• Public HTTPS endpoints — Distributed apps must use SSL for OAuth redirect URLs, the Events API Request URL, and interactivity and slash-command URLs. Use a tunnel for local development. ◆Source-backed· S2 S1Source-backedStated in official provider documentation we cite, but not observed by us.[S2] Slack Docs: Distributing your app (unlisted vs Marketplace, reinstall rules)[S1] Slack Docs: Installing with OAuth
• Distribution strategy decision — Decide between unlisted distribution (no review, throttled history and replies, Terms say it's for pilots and testing) and Marketplace (reviewed, full limits, Real-time Search API access). ◆Source-backed· S2 S3Source-backedStated in official provider documentation we cite, but not observed by us.[S2] Slack Docs: Distributing your app (unlisted vs Marketplace, reinstall rules)[S3] Slack Changelog (2025-05-29): Rate limit changes for non-Marketplace apps
• Landing, support and privacy pages, plus AI disclosures (for the Marketplace) — The privacy policy must explain third-party data handling. AI apps must disclose the model, retention, tenancy and residency, and must not use Slack data to train LLMs. ◆Source-backed· S10Source-backedStated in official provider documentation we cite, but not observed by us.[S10] Slack Docs: Slack Marketplace app guidelines and requirements
• Customer workspace or org admin — Many customer workspaces require admin approval or allow only Marketplace apps. Enterprise orgs need an Org Admin to install the app and add it to workspaces. ◆Source-backed· S2 S11Source-backedStated in official provider documentation we cite, but not observed by us.[S2] Slack Docs: Distributing your app (unlisted vs Marketplace, reinstall rules)[S11] Slack Docs: Developing for Enterprise orgs

1. 1Design around events, not history polling◆Source-backed· S3Source-backedStated in official provider documentation we cite, but not observed by us.[S3] Slack Changelog (2025-05-29): Rate limit changes for non-Marketplace apps↑ back to step

   Plan to get messages from Events API subscriptions (app_mention, message.channels, message.groups, message.im) and keep per-thread context yourself, calling conversations.replies only sparingly. Slack's own FAQ recommends the Events API for affected apps. Also decide whether you'll pursue the Marketplace.

   👤 Why you: A product/business judgement only you can make

   🤖 What an agent can do: Estimate how many history and replies calls per workspace per hour your agent makes today, and model it against 1 call/min with 15 messages per call.

   https://docs.slack.dev/changelog/2025/05/29/rate-limit-changes-for-non-marketplace-apps ↗
2. 2Create the app from a manifest◆Source-backed· S8 S7Source-backedStated in official provider documentation we cite, but not observed by us.[S8] Slack Docs: Configuring apps with app manifests[S7] Slack Docs: App manifest reference↑ back to step

   At api.slack.com/apps, choose 'Create New App' > 'From a manifest', pick the development workspace and paste the manifest (see artifacts). Alternatively, the agent can call apps.manifest.create with an app configuration token. These tokens last 12 hours, refresh via tooling.tokens.rotate, and are generated by a human under 'Your App Configuration Tokens'.

   👤 Why you: Needs your logged-in console session (2FA/CAPTCHA)

   🤖 What an agent can do: Write and validate the manifest. If a human provides a config token, create or update the app through apps.manifest.create or apps.manifest.update.

   https://api.slack.com/apps?new_app=1 ↗
3. 3Configure redirect URLs, scopes and event subscriptions◆Source-backed· S7 S2 S6Source-backedStated in official provider documentation we cite, but not observed by us.[S7] Slack Docs: App manifest reference[S2] Slack Docs: Distributing your app (unlisted vs Marketplace, reinstall rules)[S6] Slack Docs: Using token rotation↑ back to step

   Add HTTPS redirect URLs, bot scopes (chat:write, app_mentions:read, channels:history, groups:history, im:history, channels:read, users:read), the Events Request URL and bot events. Leave token rotation and PKCE off until your code supports them, because both are irreversible.

   🤖 What an agent can do: Keep the manifest in the repo as the source of truth and push changes with apps.manifest.update. Check `permissions_updated`, which signals that existing workspaces must reinstall.

   https://docs.slack.dev/reference/app-manifest ↗
4. 4Implement the multi-workspace OAuth v2 install flow◆Source-backed· S1 S11 S2Source-backedStated in official provider documentation we cite, but not observed by us.[S1] Slack Docs: Installing with OAuth[S11] Slack Docs: Developing for Enterprise orgs[S2] Slack Docs: Distributing your app (unlisted vs Marketplace, reinstall rules)↑ back to step

   Redirect to https://slack.com/oauth/v2/authorize?client_id=...&scope=<bot scopes>&redirect_uri=...&state=.... On the callback, verify state and POST code, client_id, client_secret and redirect_uri to oauth.v2.access within 10 minutes. Store the bot token keyed by team.id, or by enterprise.id when is_enterprise_install is true. Handle app_uninstalled and tokens_revoked events.

   🤖 What an agent can do: Use Bolt's built-in OAuth installer and InstallationStore, or write the handlers and a token store keyed by team_id and enterprise_id.

   https://docs.slack.dev/authentication/installing-with-oauth ↗
5. 5Install to your workspace and run end-to-end●Tested· T1 T2 S1TestedObserved directly by our agent (live endpoint probe, discovery document, URL check).Endpoint liveness only, on 2026-10-28. `curl -s -o /dev/null -w '%{http_code}' 'https://slack.com/oauth/v2/authorize?client_id=probe-invalid&scope=channels:history,chat:write&redirect_uri=https%3A%2F%2Fexample.com%2Fcb&state=xyz'` returned 200 with a client-rendered HTML shell, so an invalid client_id is not rejected at the HTTP level. `curl -s -X POST https://slack.com/api/oauth.v2.access -d 'client_id=probe-invalid&client_secret=bogus&code=bogus'` returned 200 {"ok":false,"error":"invalid_code"}. The install flow itself comes from S1.[T1] Probe: GET /oauth/v2/authorize with client_id=probe-invalid (HTTP 200 client-rendered shell)[T2] Probe: POST oauth.v2.access with bogus code (200 {"ok":false,"error":"invalid_code"})[S1] Slack Docs: Installing with OAuth↑ back to step

   Install through your own 'Add to Slack' URL, not the one-click dashboard install, to exercise OAuth. Invite the bot to a channel, @-mention it, confirm the event arrives, and post a threaded reply. Then test uninstall.

   👤 Why you: Needs your logged-in console session (2FA/CAPTCHA)

   🤖 What an agent can do: Write the test harness and log assertions. The human approves the install screen.

   https://docs.slack.dev/app-management/distribution ↗
6. 6Reach 10 active workspaces and submit to the Marketplace◆Source-backed· S9 S10Source-backedStated in official provider documentation we cite, but not observed by us.[S9] Slack Docs: Slack Marketplace review guide[S10] Slack Docs: Slack Marketplace app guidelines and requirements↑ back to step

   Once the app is used in 10 or more non-sandbox workspaces active in the past 28 days, submit it with a landing page, privacy policy, support page and AI disclosures. Include a demo video covering install, OAuth, setup, usage and uninstall, a way for reviewers to install the app themselves, and justification for each `*:history` scope. Expect enhanced review.

   👤 Why you: Waiting on the provider's reviewers

   🤖 What an agent can do: Draft the scope justifications, privacy-policy sections on Slack data handling and LLM use, the reviewer test plan and a staging-app manifest.

   https://docs.slack.dev/slack-marketplace/slack-marketplace-review-guide ↗
7. 7Activate Public Distribution (unlisted)◆Source-backed· S2 S3Source-backedStated in official provider documentation we cite, but not observed by us.S2 says 'Ensure all items in the supplied checklist are completed' but doesn't list them. The exact checklist items in the dashboard are not confirmed.[S2] Slack Docs: Distributing your app (unlisted vs Marketplace, reinstall rules)[S3] Slack Changelog (2025-05-29): Rate limit changes for non-Marketplace apps↑ back to step

   In the app's Manage Distribution page, complete the 'Share Your App with Other Workspaces' checklist (HTTPS on all URLs and the remaining dashboard items) and click 'Activate Public Distribution'. You get an Add to Slack button and a shareable install URL. From then on, new installs are subject to the non-Marketplace history and replies limits.

   👤 Why you: Needs your logged-in console session (2FA/CAPTCHA)

   🤖 What an agent can do: Pre-check the items the agent can verify: every URL is HTTPS, the redirect URLs work, and no workspace-specific token is hard-coded.

   https://docs.slack.dev/app-management/distribution#enabling ↗
8. 8After approval: confirm the full limits apply to your installs◆Source-backed· S3 S13Source-backedStated in official provider documentation we cite, but not observed by us.Whether existing unlisted installs pick up the higher limits automatically after approval is not documented in what we read.[S3] Slack Changelog (2025-05-29): Rate limit changes for non-Marketplace apps[S13] Slack Docs: Real-time Search API↑ back to step

   Marketplace-approved apps keep Tier 3 limits on history and replies and become eligible for the Real-time Search API. Slack does not say whether workspaces that installed the app while it was unlisted must reinstall to get the higher limits.

   🤖 What an agent can do: Track ratelimited errors and Retry-After values per workspace before and after approval to confirm the limits changed.

   https://docs.slack.dev/apis/web-api/real-time-search-api ↗
9. 9Customer admin approves or installs the app◆Source-backed· S2 S12Source-backedStated in official provider documentation we cite, but not observed by us.[S2] Slack Docs: Distributing your app (unlisted vs Marketplace, reinstall rules)[S12] Slack Docs: Managing app approvals↑ back to step

   In workspaces with admin approval on, a member's install becomes a request that an admin must approve. Some workspaces allow only Marketplace apps, which blocks unlisted apps outright.

   👤 Why you: Your customer's admin must act

   🤖 What an agent can do: Draft an admin-facing explainer listing every scope with a one-line justification, plus data-retention and LLM-training answers.

   https://docs.slack.dev/app-management/distribution ↗
10. 10Enterprise org: org-wide install, then add to workspaces◆Source-backed· S11 S2Source-backedStated in official provider documentation we cite, but not observed by us.[S11] Slack Docs: Developing for Enterprise orgs[S2] Slack Docs: Distributing your app (unlisted vs Marketplace, reinstall rules)↑ back to step

    If you enable org-wide deployment (org_deploy_enabled, which requires a reinstall), an Org Admin installs the app at org level. At that point the app is in no workspace. Redirect the admin to app.slack.com/manage/ENTERPRISE_ID/integrations/profile/APP_ID/workspaces/add, and pass team_id on the methods that need it.

    👤 Why you: Your customer's admin must act

    🤖 What an agent can do: Implement is_enterprise_install handling, the post-install redirect and team_id threading through API calls.

    https://docs.slack.dev/enterprise/developing-for-enterprise-orgs ↗

• BlockerHistory and replies throttled to 1 call/min with 15 messages for non-Marketplace apps◆Source-backed· S3 S4 S5 S14Source-backedStated in official provider documentation we cite, but not observed by us.[S3] Slack Changelog (2025-05-29): Rate limit changes for non-Marketplace apps[S4] Slack Changelog (2025-06-03): Clarifying rate limit changes for non-Marketplace apps[S5] Slack developer changelog archive on api.slack.com (states existing installs get new limits on March 3, 2026)[S14] Slack Docs: conversations.history method reference

  Since 29 May 2025, commercially distributed apps that are not approved for the Marketplace are limited to 1 request/minute on conversations.history and conversations.replies, and the limit parameter's maximum and default drop to 15. This applies to new apps and to new installs of existing apps. Internal customer-built apps keep 50+/min and 1,000 per call, so it works fine in your own workspace and breaks at your first customer. For existing installs the docs conflict: the archived api.slack.com changelog says the limits apply from 3 March 2026, while the current docs.slack.dev changelog says existing installs 'will not be impacted'. The method reference pages still show only 'Tier 3' with no caveat.

  Fix: Build context from Events API message events as they arrive instead of reading history on demand, budget at most 1 history or replies call per minute per workspace, honour Retry-After, and start working toward Marketplace approval early. Test rate behaviour in a second workspace, not your development workspace.

• WarningCustomer-built 'custom app' workaround violates the Terms◆Source-backed· S3Source-backedStated in official provider documentation we cite, but not observed by us.[S3] Slack Changelog (2025-05-29): Rate limit changes for non-Marketplace apps

  The obvious workaround is to have each customer create an internal app from your manifest, since internal apps aren't throttled. Slack's May 2025 Terms update says the Marketplace is the only appropriate channel for commercial distribution, explicitly including 'instructions for a templated custom app that connects to your product'.

  Fix: Don't make templated custom apps your commercial strategy. Use unlisted distribution for pilots and the Marketplace for scale.

• WarningMarketplace chicken-and-egg: 10 active workspaces before you can submit◆Source-backed· S9 S10Source-backedStated in official provider documentation we cite, but not observed by us.[S9] Slack Docs: Slack Marketplace review guide[S10] Slack Docs: Slack Marketplace app guidelines and requirements

  Submission is blocked until the app is installed on 10 or more active workspaces (used in the past 28 days, sandboxes excluded) with at least 10 weekly active users. Your first 10 customers therefore all run on the throttled unlisted limits, and review then takes up to about 12 weeks.

  Fix: Recruit 10 design-partner workspaces early, keep the pilot experience usable within the throttled limits (events-first), and prepare the submission materials in parallel.

• Warning`*:history` scopes trigger enhanced review and AI rules◆Source-backed· S10Source-backedStated in official provider documentation we cite, but not observed by us.[S10] Slack Docs: Slack Marketplace app guidelines and requirements

  Requesting `*:history`, `search:read.*`, `files:read` or `canvases:read` puts the app into enhanced review. Slack is 'unlikely to approve broad access' to message data without a clear need, and user-token `*:history` for data collection is disallowed. AI apps must not train LLMs on Slack data, must not auto-join all public channels, and must disclose the model, retention, tenancy and residency.

  Fix: Request bot-token history scopes only for channels the bot is invited to, justify each scope with a demo, and write the AI disclosures before you submit.

• WarningApp uninstalls itself when the installer leaves◆Source-backed· S2Source-backedStated in official provider documentation we cite, but not observed by us.[S2] Slack Docs: Distributing your app (unlisted vs Marketplace, reinstall rules)

  Apps that use scopes beyond bot, incoming-webhook, commands and identify (which includes any `*:history` scope) are automatically uninstalled when the user who installed them leaves the workspace or becomes a guest. The agent silently disappears for the customer.

  Fix: Subscribe to app_uninstalled and tokens_revoked, alert the customer, and encourage installs by a long-lived admin account.

• WarningToken rotation and PKCE are one-way switches◆Source-backed· S6 S2Source-backedStated in official provider documentation we cite, but not observed by us.[S6] Slack Docs: Using token rotation[S2] Slack Docs: Distributing your app (unlisted vs Marketplace, reinstall rules)

  Once enabled, token rotation cannot be turned off. Tokens then expire every 12 hours, refresh tokens are single-use, and repeated refreshes keep at most 2 active tokens. The manifest's pkce_enabled and token_management_enabled settings are also irreversible.

  Fix: Ship and test refresh handling in a staging app before enabling rotation on the production app. Bolt handles rotation automatically.

• InfoEnterprise org installs land in zero workspaces◆Source-backed· S11Source-backedStated in official provider documentation we cite, but not observed by us.[S11] Slack Docs: Developing for Enterprise orgs

  With org-wide deployment, the OAuth response has team:null, an enterprise object and is_enterprise_install:true, and the app isn't in any workspace until the Org Admin adds it. Many methods then require a team_id parameter.

  Fix: Key installations by enterprise_id, redirect the admin to the 'add to workspaces' page after OAuth, and always pass team_id.

• InfoMultiple redirect URLs require redirect_uri on both legs●Tested· T2 S1TestedObserved directly by our agent (live endpoint probe, discovery document, URL check).On 2026-10-28, `curl -s -X POST https://slack.com/api/oauth.v2.access -d 'client_id=probe-invalid&client_secret=bogus&code=bogus'` returned HTTP 200 with {"ok":false,"error":"invalid_code"}, which shows the 200-on-error behaviour. The redirect_uri rule comes from S1.[T2] Probe: POST oauth.v2.access with bogus code (200 {"ok":false,"error":"invalid_code"})[S1] Slack Docs: Installing with OAuth

  With more than one Redirect URL configured, omitting redirect_uri or sending different values to authorize and to oauth.v2.access fails with bad_redirect_uri. Slack also returns API errors as HTTP 200 with ok:false, so status-code-based error handling misses them.

  Fix: Always send the same redirect_uri in both steps and check the `ok` field on every response.

• History limits (non-Marketplace)conversations.history and conversations.replies: 1 request/min and max 15 objects per call for commercially distributed apps not approved for the Marketplace (from 29 May 2025 for new apps and new installs). Internal apps and Marketplace apps keep Tier 3 (50+/min, up to 1,000 objects).◆Source-backed· S3 S4Source-backedStated in official provider documentation we cite, but not observed by us.[S3] Slack Changelog (2025-05-29): Rate limit changes for non-Marketplace apps[S4] Slack Changelog (2025-06-03): Clarifying rate limit changes for non-Marketplace apps
• Token lifetimeBot (xoxb-) and user (xoxp-) tokens do not expire unless you enable token rotation. With rotation, tokens last 12 hours (expires_in=43200), and refresh tokens are single-use with a short grace period.◆Source-backed· S1 S6Source-backedStated in official provider documentation we cite, but not observed by us.[S1] Slack Docs: Installing with OAuth[S6] Slack Docs: Using token rotation
• Refresh endpointPOST https://slack.com/api/oauth.v2.access with grant_type=refresh_token. The endpoint is live and returns `invalid_refresh_token` for a bogus token.●Tested· T3 S6TestedObserved directly by our agent (live endpoint probe, discovery document, URL check).On 2026-10-28, `curl -s -X POST https://slack.com/api/oauth.v2.access -d 'client_id=probe-invalid&client_secret=bogus&grant_type=refresh_token&refresh_token=bogus'` returned HTTP 200 {"ok":false,"error":"invalid_refresh_token"}. Slack returns errors with HTTP 200 and ok:false.[T3] Probe: POST oauth.v2.access grant_type=refresh_token with bogus token (200 {"ok":false,"error":"invalid_refresh_token"})[S6] Slack Docs: Using token rotation
• PKCESupported. oauth.v2.access accepts code_verifier, and the manifest setting oauth_config.pkce_enabled turns PKCE on but cannot be turned off once enabled.◆Source-backed· S15 S7 S2Source-backedStated in official provider documentation we cite, but not observed by us.[S15] Slack Docs: oauth.v2.access method reference[S7] Slack Docs: App manifest reference[S2] Slack Docs: Distributing your app (unlisted vs Marketplace, reinstall rules)
• Redirect URLsHTTPS only. The redirect_uri must match or be a subdirectory of a configured URL. With multiple URLs, send the identical redirect_uri to both authorize and oauth.v2.access. Up to 1,000 per app.◆Source-backed· S1 S7Source-backedStated in official provider documentation we cite, but not observed by us.[S1] Slack Docs: Installing with OAuth[S7] Slack Docs: App manifest reference
• Auth codeExpires after 10 minutes. Validate `state` yourself.◆Source-backed· S1Source-backedStated in official provider documentation we cite, but not observed by us.[S1] Slack Docs: Installing with OAuth
• Posting ratechat.postMessage allows about 1 message/second per channel, with a workspace-wide limit. The Events API allows 30,000 deliveries per workspace per app per hour.◆Source-backed· S16Source-backedStated in official provider documentation we cite, but not observed by us.[S16] Slack Docs: Rate limits
• Marketplace review timePreliminary review up to 10 business days. Functional review up to 10 weeks (new submissions) or 6 weeks (updates). Requires 10+ active workspaces before submission.◆Source-backed· S9Source-backedStated in official provider documentation we cite, but not observed by us.[S9] Slack Docs: Slack Marketplace review guide
• Discovery lists a different authorization_endpointhttps://slack.com/openid/connect/authorize — typically the OpenID "Sign in with" flow; the URL above is the one for API access.●Tested· P1 P2TestedObserved directly by our agent (live endpoint probe, discovery document, URL check).Compared https://slack.com/.well-known/openid-configuration with the guide's authorizeUrl.[P1] Our probe: discovery check on slack.com[P2] Our probe: authorize check on slack.com
• Discovery lists a different token_endpointhttps://slack.com/api/openid.connect.token — typically the OpenID "Sign in with" flow; the URL above is the one for API access.●Tested· P1 P3TestedObserved directly by our agent (live endpoint probe, discovery document, URL check).Compared https://slack.com/.well-known/openid-configuration with the guide's tokenUrl.[P1] Our probe: discovery check on slack.com[P3] Our probe: token check on slack.com
• PKCE (from discovery document)Not advertised in the discovery document (it may only describe OpenID sign-in; check the docs)●Tested· P1TestedObserved directly by our agent (live endpoint probe, discovery document, URL check).Fetched https://slack.com/.well-known/openid-configuration[P1] Our probe: discovery check on slack.com
• Scopes advertised in discoveryopenid, profile, email●Tested· P1TestedObserved directly by our agent (live endpoint probe, discovery document, URL check).Fetched https://slack.com/.well-known/openid-configuration[P1] Our probe: discovery check on slack.com
• Endpoints observed liveAuthorize: HTTP 200; serves an HTML login/consent page; → endpoint is live (client validation may happen after login) · Token: HTTP 200; error "invalid_code"; → token endpoint is live and rejects a bogus code●Tested· P2 P3TestedObserved directly by our agent (live endpoint probe, discovery document, URL check).Requests sent with a deliberately invalid client id / code; no credentials used.[P2] Our probe: authorize check on slack.com[P3] Our probe: token check on slack.com

Live probes (no credentials)

• ✓discovery https://slack.com/.well-known/openid-configurationHTTP 200; issuer https://slack.com; authorize https://slack.com/openid/connect/authorize; PKCE methods: not advertised[P1]
• ✓authorize https://slack.com/oauth/v2/authorizeHTTP 200; serves an HTML login/consent page; → endpoint is live (client validation may happen after login)[P2]
• ✓token https://slack.com/api/oauth.v2.accessHTTP 200; error "invalid_code"; → token endpoint is live and rejects a bogus code[P3]
• ✓page https://api.slack.com/appsHTTP 200; title "Slack API: Applications | Slack"[P4]
• ✓page https://docs.slack.dev/authentication/installing-with-oauthHTTP 301; redirects to docs.slack.dev/authentication/installing-with-oauth/[P5]

Open questions

• Are installations made before 29 May 2025 of unlisted commercial apps now throttled?
  The archived api.slack.com changelog says the new limits apply to existing installations from 3 March 2026 (earlier drafts said 2 September 2025). The current docs.slack.dev changelog page says existing installations 'will not be impacted'. The conversations.history and replies reference pages show only Tier 3 with no caveat.
  To resolve: Ask Slack developer support for the current policy, and measure rate-limit responses on a pre-May-2025 install and on a fresh install of the same unlisted app.
• What exactly counts as 'commercially distributed' versus a pilot?
  The limits target apps 'commercially distributed outside of the Marketplace', and the distribution docs say unlisted apps are for pilots and testing. We found no published threshold (number of workspaces, payment) that decides which limit an install gets.
  To resolve: Measure the limits a fresh install of your distributed app gets in a second test workspace, and ask Slack support how they classify your app.
• Do installs made while the app was unlisted get the full limits automatically after Marketplace approval?
  The docs say Marketplace apps aren't affected but don't say whether earlier unlisted installs need a reinstall.
  To resolve: Ask during the Marketplace review, and compare rate-limit behaviour on a pilot workspace before and after approval.
• What does the 'Activate Public Distribution' checklist contain today?
  The distribution doc says only 'Ensure all items in the supplied checklist are completed', plus an SSL requirement for all URLs. The live checklist sits behind a login, which we did not use.
  To resolve: Open Manage Distribution in the app dashboard and record the checklist items.

Send to

No contact channel found — check https://docs.slack.dev/authentication/installing-with-oauth for developer support

Subject

OAuth integration questions — Slack

Hi Slack developer support team,

We're building an integration where AI agent bot that reads channel messages and posts replies in customers' Slack workspaces. Before we register an OAuth app and launch to customers, we couldn't find answers to the following in your documentation:

1. Are installations made before 29 May 2025 of unlisted commercial apps now throttled?
   (What we found: The archived api.slack.com changelog says the new limits apply to existing installations from 3 March 2026 (earlier drafts said 2 September 2025). The current docs.slack.dev changelog page says existing installations 'will not be impacted'. The conversations.history and replies reference pages show only Tier 3 with no caveat.)
2. What exactly counts as 'commercially distributed' versus a pilot?
   (What we found: The limits target apps 'commercially distributed outside of the Marketplace', and the distribution docs say unlisted apps are for pilots and testing. We found no published threshold (number of workspaces, payment) that decides which limit an install gets.)
3. Do installs made while the app was unlisted get the full limits automatically after Marketplace approval?
   (What we found: The docs say Marketplace apps aren't affected but don't say whether earlier unlisted installs need a reinstall.)
4. What does the 'Activate Public Distribution' checklist contain today?
   (What we found: The distribution doc says only 'Ensure all items in the supplied checklist are completed', plus an SSL requirement for all URLs. The live checklist sits behind a login, which we did not use.)

Could you point us to the right documentation or process — including whether any review or approval is needed before customers outside our own account can connect, and the typical timeline?

Thanks,
[Your name]
[Company · website]

1. S1Slack Docs: Installing with OAuthofficial
2. S2Slack Docs: Distributing your app (unlisted vs Marketplace, reinstall rules)official
3. S3Slack Changelog (2025-05-29): Rate limit changes for non-Marketplace appsofficial
4. S4Slack Changelog (2025-06-03): Clarifying rate limit changes for non-Marketplace appsofficial
5. S5Slack developer changelog archive on api.slack.com (states existing installs get new limits on March 3, 2026)official
6. S6Slack Docs: Using token rotationofficial
7. S7Slack Docs: App manifest referenceofficial
8. S8Slack Docs: Configuring apps with app manifestsofficial
9. S9Slack Docs: Slack Marketplace review guideofficial
10. S10Slack Docs: Slack Marketplace app guidelines and requirementsofficial
11. S11Slack Docs: Developing for Enterprise orgsofficial
12. S12Slack Docs: Managing app approvalsofficial
13. S13Slack Docs: Real-time Search APIofficial
14. S14Slack Docs: conversations.history method referenceofficial
15. S15Slack Docs: oauth.v2.access method referenceofficial
16. S16Slack Docs: Rate limitsofficial
17. S17Slack Docs: app_mentions:read scopeofficial
18. S18Slack Docs: channels:read scopeofficial
19. S19Slack Docs: users:read scopeofficial
20. T1Probe: GET /oauth/v2/authorize with client_id=probe-invalid (HTTP 200 client-rendered shell)probe
21. T2Probe: POST oauth.v2.access with bogus code (200 {"ok":false,"error":"invalid_code"})probe
22. T3Probe: POST oauth.v2.access grant_type=refresh_token with bogus token (200 {"ok":false,"error":"invalid_refresh_token"})probe
23. T4Probe: Sign in with Slack OIDC discovery (200; authorization_code only, scopes openid/profile/email; not used for bot installs)probe
24. P1Our probe: discovery check on slack.comprobe
25. P2Our probe: authorize check on slack.comprobe
26. P3Our probe: token check on slack.comprobe
27. P4Our probe: page check on api.slack.comprobe
28. P5Our probe: page check on docs.slack.devprobe