Slack

Overview

Connect your users to Slack workspaces for messaging, channel management, file sharing, and notifications.

Alter’s Slack adapter requests Bot Token Scopes through Slack’s OAuth scope parameter and stores the resulting bot token (xoxb-... without token rotation, xoxe.xoxb-... with rotation). The end user approves the workspace installation, but API calls act as the Slack app bot — Alter does not request user_scope or use a user token for this provider.

Property	Value
Provider ID	slack
Category	Communication
PKCE	Not supported
Token refresh	Automatic (rolling - new token each refresh)
Access token lifetime	12 hours
Redirect URI	Shown in Developer Portal

Note

Slack uses rolling refresh tokens - each refresh returns a new refresh token and the old one is revoked. Alter Vault handles this automatically.

Step 1: Create a Slack App

Go to Slack API

Navigate to api.slack.com/apps and click Create New App.

Choose creation method

Select From scratch. Enter:

• App Name: The application name (e.g., “My App Integration”)
• Pick a workspace: Select a development workspace for testing
• Click Create App

Get credentials

Go to Settings > Basic Information:

• Scroll to App Credentials
• Copy the Client ID and Client Secret

Configure OAuth redirect

Go to OAuth & Permissions in the sidebar:

• Under Redirect URLs, click Add New Redirect URL
• Copy the Redirect URI from the Developer Portal
• Click Save URLs

Enable token rotation

Go to OAuth & Permissions:

• Scroll to Token Rotation
• Click Opt in to token rotation

This enables refresh tokens, which Alter Vault uses to automatically keep access tokens fresh.

Add bot scopes

Go to OAuth & Permissions:

• Scroll to Scopes > Bot Token Scopes
• Add the scopes the application needs (see Available Scopes below)
• Do not add them only under User Token Scopes; Alter’s Slack consent URL requests bot scopes

Enable external workspace installation when needed

A newly created Slack app can only be installed in its associated development workspace. If users from other workspaces must authorize it, complete Slack’s distribution checklist and enable Manage Distribution → Activate Public Distribution. An unlisted distributed app is sufficient for private pilots; Slack Marketplace review is a separate publication step. See Slack’s app-distribution guide.

Warning

Token rotation is optional. Without it, Slack issues a non-expiring xoxb-... bot token that remains valid until it is revoked or the app is uninstalled. With rotation enabled, Slack issues a 12-hour xoxe.xoxb-... access token plus a rolling refresh token; Alter Vault refreshes and replaces both automatically.

Step 2: Add to Alter Vault

Open the Developer Portal

Go to portal.alterauth.com and navigate to the application.

Add Slack provider

Go to OAuth Providers > Add Provider > Slack.

Enter credentials

Slack opens directly in custom-credential mode. Enter:

• Client ID: Paste your Slack Client ID
• Client Secret: Paste your Slack Client Secret

Select scopes

Choose the bot token scopes the application needs.

Save

Click Save. The provider is now active.

Step 3: Test It

After a user connects via Alter Connect, use the returned grant_id to make API calls:

With the default chat:write scope, first invite the Slack app to the destination channel with /invite @<your Slack app name>. A channel returned by conversations.list is not necessarily one the bot has joined. Select the broader chat:write.public scope only when the app should be able to post to any public channel without an invite.

chat:write.public depends on chat:write. The portal selects the prerequisite automatically and removes the dependent scope if the prerequisite is removed; the CLI and backend reject an invalid combination.

from alter_sdk import App, HttpMethod

async with App(
    api_key="alter_key_...",
    caller="my-agent",
) as alter_app:
    response = await alter_app.request(
        HttpMethod.POST,
        "https://slack.com/api/chat.postMessage",
        grant_id=grant_id,
        json={"channel": "#general", "text": "Hello from Alter Vault!"},
    )
    data = response.json()
    if data.get("ok"):
        print("Message sent!")
    else:
        print(f"Error: {data.get('error')}")

Available Scopes

Reading

Scope	Description
channels:read	Bot token: list public channels; listing does not mean the bot has joined them
channels:history	View messages and other content in public channels
groups:read	View basic information about private channels
im:read	View basic information about direct messages
mpim:read	View basic information about group direct messages
users:read	View people in a workspace
users:read.email	View email addresses of people in this workspace
team:read	View the name, email domain, and icon for workspaces
files:read	View files shared in channels and conversations
reactions:read	View emoji reactions in channels and conversations
app_mentions:read	View messages that directly mention your app

Writing

Scope	Description
chat:write	Bot token: post only where the Slack app is already a member
chat:write.public	Bot token: post in public channels without joining first; requires chat:write
chat:write.customize	Bot token: send messages with a customized username and avatar; requires chat:write
channels:manage	Manage public channels and create new ones
channels:join	Join public channels in a workspace
groups:write	Manage private channels that your app has been added to
im:write	Start direct messages with people
mpim:write	Start group direct messages with people
files:write	Upload, edit, and delete files
reactions:write	Add and remove emoji reactions

Other

Scope	Description
commands	Add shortcuts and slash commands
incoming-webhook	Post messages to specific channels via incoming webhooks

Common API Endpoints

Use Case	Method	URL
Send a message	POST	https://slack.com/api/chat.postMessage
List channels	GET	https://slack.com/api/conversations.list
Get channel history	GET	https://slack.com/api/conversations.history
List users	GET	https://slack.com/api/users.list
Get file upload URL	POST	https://slack.com/api/files.getUploadURLExternal
Complete file upload	POST	https://slack.com/api/files.completeUploadExternal
Add a reaction	POST	https://slack.com/api/reactions.add

Notes

• Slack uses bot tokens (xoxb-... without rotation, xoxe.xoxb-... with rotation). These act on behalf of the app, not the user.
• Slack returns HTTP 200 for API-level failures. Always require ok: true; ok: false with error: "not_in_channel" means the bot must be invited or granted chat:write.public.
• Non-rotation xoxb-... access tokens do not expire. Rotation xoxe.xoxb-... access tokens expire after 12 hours; Alter Vault automatically refreshes them using the rolling refresh token.
• Slack scopes are comma-separated (unlike most providers which use spaces). Alter Vault handles this automatically.
• See the Slack OAuth installation guide for details.

Policy-cataloged operations

Alter policy rules can target these attested operations and families for operation-level and parameter-aware controls.

Operation ID	Families	Method	Provider path
chat_postMessage	send	POST	/api/chat.postMessage
chat_postEphemeral	send	POST	/api/chat.postEphemeral
chat_scheduleMessage	send	POST	/api/chat.scheduleMessage
chat_meMessage	send	POST	/api/chat.meMessage
chat_update	write	POST	/api/chat.update
chat_delete	delete	POST	/api/chat.delete
chat_deleteScheduledMessage	delete	POST	/api/chat.deleteScheduledMessage
chat_getPermalink	read	GET	/api/chat.getPermalink
chat_scheduledMessages_list	read	GET	/api/chat.scheduledMessages.list
conversations_create	write	POST	/api/conversations.create
conversations_archive	write	POST	/api/conversations.archive
conversations_rename	write	POST	/api/conversations.rename
conversations_join	write	POST	/api/conversations.join
conversations_leave	write	POST	/api/conversations.leave
conversations_open	write	POST	/api/conversations.open
conversations_invite	admin	POST	/api/conversations.invite
conversations_kick	admin	POST	/api/conversations.kick
conversations_list	read	GET	/api/conversations.list
conversations_history	read	GET	/api/conversations.history
users_list	read	GET	/api/users.list
users_info	read	GET	/api/users.info
users_lookupByEmail	read	GET	/api/users.lookupByEmail
files_upload	write	POST	/api/files.upload
files_delete	delete	POST	/api/files.delete
reactions_add	write	POST	/api/reactions.add
reactions_remove	write	POST	/api/reactions.remove
pins_add	write	POST	/api/pins.add
pins_list	read	GET	/api/pins.list
search_messages	read	GET	/api/search.messages
auth_test	read	GET	/api/auth.test
team_info	read	GET	/api/team.info