OAuth providers

Slack

Set up Slack OAuth for messaging, channels, and workspace access

Overview

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

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

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)

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

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:

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`	View public channel info
`channels:history`	View messages in public channels
`groups:read`	View private channel info
`im:read`	View direct message info
`mpim:read`	View group DM info
`users:read`	View people in workspace
`users:read.email`	View email addresses of workspace members
`team:read`	View workspace name, domain, and icon
`files:read`	View files shared in channels
`reactions:read`	View emoji reactions
`app_mentions:read`	View messages mentioning the application

Writing

Scope	Description
`chat:write`	Post messages in approved channels
`chat:write.public`	Post to any public channel
`chat:write.customize`	Post with custom username and avatar
`channels:manage`	Manage and create public channels
`channels:join`	Join public channels
`groups:write`	Manage private channels
`im:write`	Start direct messages
`mpim:write`	Start group DMs
`files:write`	Upload, edit, and delete files
`reactions:write`	Add and remove emoji reactions

Other

Scope	Description
`commands`	Add slash commands
`incoming-webhook`	Post 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-...) 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.