Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.alterauth.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Connect your users to Slack workspaces for messaging, channel management, file sharing, and notifications.
PropertyValue
Provider IDslack
PKCENot supported
Token refreshAutomatic (rolling - new token each refresh)
Access token lifetime12 hours
Redirect URIShown in Developer Portal
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

1

Go to Slack API

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

Choose creation method

Select From scratch. Enter:
  • App Name: Your app name (e.g., “My App Integration”)
  • Pick a workspace: Select a development workspace for testing
  • Click Create App
3

Get your credentials

Go to Settings > Basic Information:
  • Scroll to App Credentials
  • Copy the Client ID and Client Secret
4

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
5

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.
6

Add bot scopes

Go to OAuth & Permissions:
  • Scroll to Scopes > Bot Token Scopes
  • Add the scopes your app needs (see Available Scopes below)
Token rotation must be enabled for Alter Vault to automatically refresh Slack tokens. Without it, users will need to re-authorize every 12 hours.

​
Step 2: Add to Alter Vault

1

Open the Developer Portal

Go to portal.alterauth.com and navigate to your app.
2

Add Slack provider

Go to OAuth Providers > Add Provider > Slack.
3

Enter credentials

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

Select scopes

Choose the bot token scopes your app needs.
5

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: 
from alter_sdk import AlterVault, HttpMethod

async with AlterVault(
    api_key="alter_key_...",
    caller="my-agent",
) as vault:
    response = await vault.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

ScopeDescription
channels:readView public channel info
channels:historyView messages in public channels
groups:readView private channel info
im:readView direct message info
mpim:readView group DM info
users:readView people in workspace
users:read.emailView email addresses of workspace members
team:readView workspace name, domain, and icon
files:readView files shared in channels
reactions:readView emoji reactions
app_mentions:readView messages mentioning your app

​
Writing

ScopeDescription
chat:writePost messages in approved channels
chat:write.publicPost to any public channel
chat:write.customizePost with custom username and avatar
channels:manageManage and create public channels
channels:joinJoin public channels
groups:writeManage private channels
im:writeStart direct messages
mpim:writeStart group DMs
files:writeUpload, edit, and delete files
reactions:writeAdd and remove emoji reactions

​
Other

ScopeDescription
commandsAdd slash commands
incoming-webhookPost via incoming webhooks

​
Common API Endpoints

Use CaseMethodURL
Send a messagePOSThttps://slack.com/api/chat.postMessage
List channelsGEThttps://slack.com/api/conversations.list
Get channel historyGEThttps://slack.com/api/conversations.history
List usersGEThttps://slack.com/api/users.list
Get file upload URLPOSThttps://slack.com/api/files.getUploadURLExternal
Complete file uploadPOSThttps://slack.com/api/files.completeUploadExternal
Add a reactionPOSThttps://slack.com/api/reactions.add

​
Notes

  • Slack uses bot tokens (xoxb-...) by default. These act on behalf of the app, not the user.
  • Access tokens expire every 12 hours. With token rotation enabled, 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.
  • The Slack API always returns HTTP 200, even on errors. Check the ok field in the response body to determine success or failure.