Register a Slack app

Before your users can connect their workspaces, Slack needs an app that you own and they install. You register it once, it takes about five minutes, and every workspace that connects afterwards goes through the same app. Only connecting your own workspace? Set up Slack is shorter: an app from a prefilled manifest and the bot token it shows you. Every Slack link below opens in a new tab, so this page stays where you left it.

Create the app

Open api.slack.com/apps and click Create an App.

Slack's Your Apps page, with a green Create an App button in the middle.

Choose From scratch.

The Create an app dialog, offering From a manifest and From scratch.

Name the app and pick the workspace to develop it in, then click Create App. Your users see this name on the consent screen and on every message the app posts. You can rename the app later, but you can’t move it to another workspace.

The Name app & choose workspace dialog, with Example App as the app name and a workspace selected.

Prefer a manifest? Use the one on Set up Slack, which already has the pack’s scopes, and add your callback under oauth_config: "redirect_urls": ["https://app.example.com/oauth/slack/callback"]. That does steps 2 and 3 for you.

Add your redirect URL

In the sidebar, open OAuth & Permissions. Under Redirect URLs, click Add New Redirect URL, enter your app’s callback route, click Add, then Save URLs.

The Redirect URLs section of OAuth & Permissions, listing https://app.example.com/oauth/slack/callback, with Add New Redirect URL and Save URLs buttons.

Slack only sends the browser back to a URL on this list. Register the exact redirect_uri your flow sends, scheme and path included.

Add the bot scopes

On the same page, scroll to Scopes. Under Bot Token Scopes, click Add an OAuth Scope once for each scope your tools need.

Bot Token Scopes listing channels:history, chat:write and users:read, each with its description, and an Add an OAuth Scope button.

The pack’s tools declare nineteen scopes:

slack scopes

channels:history  channels:join  channels:manage  channels:read
channels:write.invites  chat:write  groups:history  groups:read
groups:write  groups:write.invites  im:history  im:read  im:write
mpim:history  mpim:read  mpim:write  reactions:read  reactions:write
users:read

scopes_for(slack.TOOLS) returns the same list, so if you only hand out some of the tools, ask it for theirs and leave the rest off. The link your app builds asks for scopes too, and Slack refuses to grant a scope the app hasn’t been given here.

Copy the client ID and secret

Open Basic Information and scroll to App Credentials. Copy the Client ID, then click Show next to Client Secret and copy that too. The signing secret and verification token are for events, which the flow doesn’t use.

Basic Information's App Credentials: App ID and Client ID (hidden), Client Secret and Signing Secret masked with Show and Regenerate buttons.

export SLACK_CLIENT_ID=1234567890.1234567890
export SLACK_CLIENT_SECRET=...

Keep the secret on your server. Anyone who has it can complete a grant as your app.

Turn on public distribution

Until you do this, only the workspace you picked in step 1 can install the app. Open Manage Distribution, work through its checklist (it checks that the redirect URL uses HTTPS and that nothing is hard-coded), then click Activate Public Distribution.Distributing the app isn’t the same as listing it in the Slack Marketplace. Workspaces install it from your own link, and you only need Slack’s review if you also want a Marketplace listing.

Connect a workspace

Your app’s “Connect Slack” button opens the link that flow.authorize() builds. The user picks a workspace, reviews what the app can see and do, and clicks Allow.

Slack's consent screen: a workspace picker, what Example App can view and the actions it can take, and Cancel and Allow buttons.

slack_connect.py

from charter.auth import OAuth2Flow

flow = OAuth2Flow(
    SLACK,  # the server constant, from /auth/providers/slack
    client_id=os.environ["SLACK_CLIENT_ID"],
    client_secret=os.environ["SLACK_CLIENT_SECRET"],
    redirect_uri="https://app.example.com/oauth/slack/callback",
)
request = flow.authorize(SLACK_SCOPES)  # request.url is the link to open

# At the callback, after checking state:
grant = await flow.exchange(code, code_verifier=verifier, expect_refresh_token=False)
# grant.access_token is that workspace's xoxb- bot token: store it against the user.

expect_refresh_token=False is there because an app with token rotation off gets a bot token that never expires and no refresh token comes with it. Slack’s provider page covers turning rotation on and what changes when you do.

When it does not work

“redirect_uri did not match any configured URIs”

The flow sent a redirect_uri that isn’t on the app’s list. Add it under OAuth & Permissions → Redirect URLs exactly as the flow sends it, then Save URLs. Forgetting that last click is the usual cause.

A workspace other than yours can't install the app

Public distribution is off, so only the development workspace can install. See step 5.

“invalid_scope”, or missing_scope from a tool later

The link asked for a scope the app doesn’t have, or a tool needs a scope the grant doesn’t cover. Add it under Bot Token Scopes, then have that workspace connect again. A grant only covers the scopes it was issued for.

not_in_channel

The bot reads only the channels it has been invited to. In the channel, type /invite @your-app.

Slack — the server constant, both token shapes, and refresh under rotation
Getting the grant — the two routes, state and PKCE, inside your app
Every pack — what each pack’s users connect with, and what you store
Set up Slack — your own workspace, from a manifest

Get started

Declaring a tool

The boundary

Authentication

Using your tools

Optimization

Running it

Guarantees

When it does not work

​When it does not work

​Related

When it does not work

Related