OAuth Readiness
Chat·slack.com·researched guide, 2026-10-30

Slack (Slack app, OAuth v2)

Building is easy: create an app at api.slack.com/apps (an agent can write the manifest), add bot scopes, and any workspace can install it via an 'Add to Slack' link once Manage Distribution is on, with no Marketplace review. The catch is reading history: since 29 May 2025, commercially distributed apps not approved for the Slack Marketplace get conversations.history and conversations.replies at 1 request per minute and 15 messages per call. Marketplace approval needs 10+ active workspaces first and then up to 10 weeks of review.

Difficulty
moderate
First token
15 min
Real users
Same day (unlisted)
Cost
Free

Review: none to distribute an unlisted app; Slack Marketplace review to lift the history rate limit, and Slack's API Terms name the Marketplace as the channel for commercial distribution

Timing: same day for posting alerts to other workspaces (unlisted distribution); roughly 3-4 months if you need Marketplace approval for full history reads (reach 10 active workspaces, then up to 10 business days preliminary + up to 10 weeks functional review).

Cost: free (some AI/agent features need a paid Slack plan on the installing workspace)

Verdict evidence sourceds6s2s4s10

Before you start

Iskaria readiness: 5 of 5 profile items in place
edit profile
  • for buildA Slack account and a development workspace (the app's home workspace)sourceds7
  • for buildHTTPS OAuth redirect URL (https://app.iskaria.com/api/oauth/slack/callback). The localhost URL in the profile is http and will be rejected; use an HTTPS tunnel for local dev.✓ Iskaria has itsourceds1s6
  • for launchPublic landing page explaining the Slack app and how to install it (Marketplace only)✓ Iskaria has itsourceds5
  • for launchPrivacy policy stating data collected, use, retention, and how to access/delete it; must also disclose LLM model, retention and data residency for AI apps (Marketplace only)✓ Iskaria has itsourceds5
  • for launchPublic support page with a contact method, no account required, replies within 2 business days (Marketplace only)✓ Iskaria has itsourceds5
  • for launch10 or more active workspaces with the app installed before Marketplace submissionsourceds4
  • for launchApp icon. MISSING: the profile has no exported square PNG (logo.square512Png is null).✓ Iskaria has itinferred
Test mode:availablesourceds2s3s10

An app works immediately in its development workspace. Installed only there (not distributed), it counts as an internal customer-built app and keeps Tier 3 history limits (50+ requests/min, up to 1,000 objects). Free Developer Program sandboxes cover paid-only AI features.

Who does what

Agentcan do for you
  • Write the full app manifest (name, description, bot scopes, HTTPS redirect URLs, events/Socket Mode)
  • Implement the OAuth v2 install flow, per-workspace token storage and token rotation
  • Build alert posting with per-channel throttling and event-driven reading instead of history polling
  • Draft the Marketplace scope justifications, landing page, privacy-policy LLM section and support page
Youmust take over
  • Log in at api.slack.com/apps and create the app (paste the manifest), or issue an app configuration token
  • Install to the development workspace and copy client id/secret/signing secret into server env
  • Activate public distribution
  • Get 10 clinic workspaces actively using the app before a Marketplace submission, then submit and answer reviewers
  • Decide whether Iskaria's use counts as commercial distribution under Slack's API Terms

Steps

Buildcreate the app and credentials
  1. 1Have the agent write the app manifestAgent5 minsourceds7

    Generate a YAML/JSON manifest: display_information (name, description), features.bot_user, oauth_config.redirect_urls (HTTPS) and oauth_config.scopes.bot (chat:write, chat:write.public, channels:read, channels:history), settings (event subscriptions or Socket Mode, token rotation). Keep user scopes empty unless the agent must act as a person.

    display_information.nameIskaria
    display_information.descriptionIskaria is a multi-clinic operations console with an AI assistant. Clinic staff connect their business accounts so the assistant can answer patient messages, track leads and report on marketing performance.Tailor to useCases.slack: lead alerts and daily summaries.
    oauth_config.redirect_urls["https://app.iskaria.com/api/oauth/{provider}/callback","http://localhost:3000/api/oauth/{provider}/callback"]HTTPS only.
    oauth_config.scopes.bot
  2. 2Create the app from the manifestYou3 minsourceds7

    api.slack.com/apps > Create New App > From a manifest > pick the development workspace > paste the manifest > Next > Create. ('From scratch' also works: name + workspace, then add scopes under OAuth & Permissions.) Fully automatable later via apps.manifest.create with an app configuration token (12-hour lifetime, rotated with tooling.tokens.rotate).

    https://api.slack.com/apps
  3. 3Decide bot token vs user tokenYou2 minsourceds1

    Use the bot token (xoxb-, from `scope`) for posting alerts and reading channels the bot is in: it survives the installing user leaving. Request user scopes (`user_scope`, xoxp- token under authed_user) only for actions a bot cannot do, such as search:read.

  4. 5Implement OAuth v2 for other workspacesAgent1-2 hsourceds1

    Send users to https://slack.com/oauth/v2/authorize?client_id=...&scope=...&redirect_uri=...&state=...; on the callback exchange the code with oauth.v2.access using client id + secret. Store the bot token per workspace (team.id), encrypted server-side. Optionally enable token rotation (expiring access token + refresh token).

  5. 8Optional: add AI agent featuresAgent drafts, you submit30 minsourceds10

    Enable the Agents feature in the app settings sidebar, add the assistant:write scope (top-nav entry point, 'agent' label) and subscribe to the assistant/agent events. Some of these features need a paid plan on the installing workspace.

Testworks for you and test users
  1. 4Install to your workspace and post a test alertYou5 minsourceds8

    OAuth & Permissions > Install to Workspace, copy the bot token into server env, invite the bot to a channel (/invite @Iskaria) and call chat.postMessage. Posting is limited to about 1 message per second per channel.

Launchreview and approval for real users
  1. 6Turn on distributionYou10 minsourceds6

    Manage Distribution > Share Your App with Other Workspaces: complete the checklist (HTTPS redirect URLs, no hard-coded tokens) and click Activate Public Distribution. You get an 'Add to Slack' button and shareable install URL. Any workspace can install now, without Marketplace approval; the app is 'unlisted'.

  2. 7Design reads around the non-Marketplace limitAgent1-3 hsourceds2s5

    As an unlisted distributed app, every new install gets conversations.history and conversations.replies at 1 request/minute, max 15 messages. Prefer Events API / Socket Mode (message.channels events) and store only what you need, instead of polling history. Posting alerts is unaffected.

  3. 9Optional: submit to the Slack MarketplaceAgent drafts, you submit1-2 days prepsourceds4s5

    Once installed on 10+ active workspaces (used in the last 28 days): prepare landing page, privacy policy (incl. LLM disclosures), support page, a per-scope justification, and a test install path for reviewers (Slack cannot access your workspaces). Submit from the app's Marketplace settings. Preliminary feedback within ~10 business days; functional review up to 10 weeks (6 for resubmissions).

Scopes an agent typically needs

ScopeUsed forReview tierEvidence
chat:writePost lead alerts and daily summaries as the bot in channels it is inbasicsourceds8
chat:write.publicPost to a public channel without inviting the bot firstbasicsourceds8
channels:readList channels so staff can pick where alerts gobasicinferred
channels:historyRead public-channel messages the agent needs as context
*:history scopes trigger enhanced Marketplace review; outside the Marketplace the method is throttled to 1 req/min, 15 messages.
sensitivesourceds9s5s2
groups:historySame, for private channels the bot is invited to
Skip it if alerts only go to public channels.
sensitivesourceds9s5

What can slow you down or block approval

can block launchHistory reads throttled to 1/min and 15 messages for non-Marketplace appssourceds2s3

Since 29 May 2025, commercially distributed apps not approved for the Marketplace (new apps and new installs of existing ones) get conversations.history and conversations.replies at 1 request per minute with limit capped at 15. Marketplace apps and internal customer-built apps keep 50+ requests/minute and 1,000 objects. Iskaria installs into many clinic workspaces, so it is in the throttled class.

Workaround: Use the Events API / Socket Mode to receive messages as they happen; pursue Marketplace approval if deep history reads are core.

slows you downAPI Terms: Marketplace is the channel for commercial distributionsourceds2s6

Slack's updated API Terms (effective 29 May 2025 for new apps, 30 June 2025 for older ones) call the Marketplace the only appropriate channel for commercially distributing apps, including templated custom apps that connect to a product. Unlisted distribution still works technically, but per-clinic 'internal' apps built from your manifest to dodge the limit are explicitly in scope.

Workaround: Treat unlisted distribution as a pilot; plan for Marketplace review once 10 workspaces are active.

slows you downMarketplace review is long and has an entry barsourceds4s5

Requires 10+ active workspaces before submission; preliminary review up to ~10 business days, functional review up to 10 weeks for new apps. Admin scopes are unlikely to be approved, future-use scopes are rejected, and *:history / files:read / search:read.* get enhanced review.

slows you downAI app rules in Marketplace guidelinessourceds5

No training LLMs on Slack data; disclaimer about inaccurate outputs on the landing page and long description; disclose model, retention and data residency; no consequential decisions without human review; don't store Slack data, store metadata and fetch in real time; MCP-server-only apps are unsuitable.

infoRedirect URL must be HTTPSsourceds1

Redirect URLs must use HTTPS and cannot contain '#'; the profile's http://localhost callback will not work.

Workaround: Use an HTTPS tunnel or a preview deployment for local OAuth testing.

infoLegacy custom bots stopped working 31 March 2025sourceds11

Do not build on legacy bot tokens or classic apps. Classic-app deprecation is paused, but new work should be a (granular-permission) Slack app.

What we checked

ClaimHowResult
Non-Marketplace apps get conversations.history/replies at 1 request/min and 15 objects from 29 May 2025
Applies to commercially distributed (unlisted) apps: new apps and new installs. Internal customer-built apps keep 50+/min and 1,000 objects.
Fetched Slack's changelog entry and the 3 June 2025 clarificationconfirmed
Existing installs of unlisted apps were throttled from 3 March 2026
Slack's changelog as fetched still says existing installations are not affected; the March 2026 date appears only in third-party sources.
Compared community posts (DEV, vendor docs) with Slack's own changelog pageunverified
conversations.history is Tier 3
The reference still says Tier 3 (50+/min) and does not mention the non-Marketplace Tier 1 limit, so the reference page alone misleads agents that read history.
Fetched the method referencecorrected
Classic apps are being shut down
Legacy custom bots stopped 31 March 2025, but the classic-app shutdown (rescheduled several times through November 2026) is now paused.
Fetched the 2024 deprecation changelogcorrected
Marketplace review takes weeks
Up to 10 business days preliminary, up to 10 weeks functional (6 for resubmissions); 10 active workspaces required first.
Fetched the Marketplace review guideconfirmed
Non-Marketplace commercially distributed apps: conversations.history/replies at 1 req/min, limit 15, since 29 May 2025 for new apps and new installs; Marketplace and internal apps keep 50+/min, 1,000 objects
Existing installations of older non-Marketplace apps kept the old limits per the changelog.
Independent check: re-fetched the Slack changelog of 2025-05-29 on 2026-10-30; the method page still shows Tier 3 (50+/min) as the defaultconfirmed
Marketplace: 10+ active workspaces to submit; preliminary review up to 10 business days; functional review up to 10 weeks for new apps; *:history, files:read, search:read.* get enhanced review
Active = used in the past 28 days; the 10-week clock starts when a reviewer is assigned.
Independent check: fetched docs.slack.dev Marketplace review guide and app guidelines on 2026-10-30confirmed
OAuth endpoint behaviour (discovery metadata, PKCE, dynamic registration, unknown-client handling)
Slack's discovery covers only Sign in with Slack (OIDC), not the v2 bot-scope flow; no PKCE methods advertised and no dynamic registration. /oauth/v2/authorize with an unknown client_id returns HTTP 200 with an HTML page.
Endpoint probe: node scripts/probe.ts on 2026-10-30confirmed
Still uncertain
  • Whether existing installs of unlisted apps also became throttled on 3 March 2026: community posts say so, but Slack's own changelog (as fetched 2026-10-30) still says existing installs are not affected.
  • Marketplace review times are Slack's stated maximums; real waits are not documented.
  • Slack does not define 'internal customer-built app' precisely, so whether a manifest-cloned per-clinic app keeps Tier 3 is unclear (and the Terms cover templated custom apps).
  • Exact Manage Distribution checklist items and app-icon size requirements were not fetched this session.
  • Which AI/agent features need a paid plan is not itemised in the doc fetched.

Sources

  1. s1
    Installing with OAuth · official-docs · accessed 2026-10-30
    “exchange the code for an access token”
  2. s2
    Rate limit changes for non-Marketplace apps (changelog, 29 May 2025) · provider-policy · accessed 2026-10-30
    “limited to 1 request per minute, unless they are approved for the Slack Marketplace”
  3. s3
    Clarifying rate limit changes for non-Marketplace apps (changelog, 3 June 2025) · provider-policy · accessed 2026-10-30
    “Any internal customer-built apps will maintain their existing rate limits and will not be subject to the new posted limits.”
  4. s4
    Slack Marketplace review guide · provider-policy · accessed 2026-10-30
    “Your app has been installed on 10 or more active workspaces.”
  5. s5
    Slack Marketplace app guidelines and requirements · provider-policy · accessed 2026-10-30
    “DON'T include scopes in your submitted app intended for future functionality.”
  6. s6
    Distributing your app · official-docs · accessed 2026-10-30
    “apps intended for commercial distribution should be submitted and approved for listing in the Slack Marketplace.”
  7. s7
    Configuring apps with app manifests · official-docs · accessed 2026-10-30
    “Manifests are YAML or JSON-formatted configurations bundles for Slack apps.”
  8. s8
    chat.postMessage method · official-docs · accessed 2026-10-30
    “It will generally allow an app to post 1 message per second to a specific channel.”
  9. s9
    conversations.history method · official-docs · accessed 2026-10-30
    “Tier 3: 50+ per minute”
  10. s10
    Developing AI apps / agents · official-docs · accessed 2026-10-30
    “Developing and using some AI features require a paid plan, despite being visible in the app settings on any plan.”
  11. s11
    Discontinuing support for legacy custom bots and classic apps (changelog) · provider-policy · accessed 2026-10-30
    “Classic apps deprecation has been paused”
  12. s12
    Slack Just Throttled Your OpenClaw Agent (DEV Community) · community · accessed 2026-10-30
    “That grace period ended March 3, 2026.”
  13. s13
    Endpoint probe, 2026-10-30 · our-test · accessed 2026-10-30
    “openid-configuration: grant_types [authorization_code]; scopes [openid, profile, email]; no code_challenge_methods_supported; no registration_endpoint”
Something wrong or outdated? Re-run the agent for Slack (Slack app, OAuth v2)