titledescriptionupdated_date
Slack APIHow to generate a Slack API key for accessing public channels.2025-10-24T16:45:21Z

What we need

[] Bot User OAuth Token: The `xoxb-` token generated during Step 3.
[] Workspace URL: The URL of the Slack workspace (e.g., `your-workspace.slack.com`).

Introduction

This document outlines the standard procedure for creating a Slack User OAuth Token. This token grants an application permission to interact with a Slack workspace, such as reading messages from public channels.

Security Warning

The generated API token is a sensitive credential. Treat it like a password and never share it in insecure locations like public chat channels. Use a secure secret management system, such as a password manager or a dedicated secrets vault, to store and transmit the token.

Security Scopes in Slack

Here is official slack documentation on scopes

Step 1: Create a Slack Application

Option 1: Use a Slack manifest File

The following is a Slack manifest file that includes the wides scopes needed. You are welcome to take sections out between the comments, however all scopes listed under a comment must be allowed for that data type to completely be ingested

For example, to ingest public channel information, you must give both history and read access. One without the other isn’t sufficient to ingest slack public channel data.

Step 1: Create the bot with the Manifest File

  • Click on “From Manifest”
  • Select the Slack workspace. There is one per slack workspace
  • Paste in the manifest file.

The following is a manifest file that gives the widest permissions to the bot. You may remove selectively the groups of content you do not want Parable to ingest.

_metadata:
  major_version: 2
  minor_version: 1
display_information:
  name: Parable Manifest Ingestion
features:
  app_home:
    home_tab_enabled: true
    messages_tab_enabled: true
    messages_tab_read_only_enabled: false
  bot_user:
    display_name: Parable Ingestion
    always_online: false
oauth_config:
  scopes:      
    bot:
      #ELSE: Pull public messages
      - channels:history
      - channels:read 

      # Pull private group messages
      - groups:read
      - groups:history

      # Get all organization users
      - users:read
      - users:read.email
      - users.profile:read

      # Get Team
      - team:read

      # Get chat logs
      - calls:read
      
      # Private Group Messages
      - mpim:history
      - mpim:read

      # Get slack list
      - lists:read
settings:
  event_subscriptions:
    bot_events:
      - message.channels
  interactivity:
    is_enabled: false
  org_deploy_enabled: true
  socket_mode_enabled: true
  • Click Create

Option 2: Do it From Scratch

Step 1: Create the App

  1. Navigate to the Slack App Directory: Go to https://api.slack.com/apps.
  2. Initiate App Creation: Click Create New App and select the From scratch option.
  3. Define App Details:
    • App Name: Assign a descriptive name (e.g., Parable's API Access).
    • Workspace: Select the target Slack workspace for the integration.
  4. Confirm Creation: Click Create App.

Step 2: Assign Permissions (Scopes)

  1. Navigate to Oauth & Permissions: From the app’s settings menu on the left, select OAuth & Permissions.
  2. Add Bot Token Scopes: Scroll to the Scopes section and, under Bot Token Scopes, click Add an OAuth Scope.
      # Read public channel history
      - channels:history
      - channels:read 

      # Pull private group messages
      - groups:read
      - groups:history

      # Get all organization users
      - users:read
      - users:read.email
      - users.profile:read

      # Get Team
      - team:read

      # Get chat logs
      - calls:read
      
      # Private Group Messages
      - mpim:history
      - mpim:read

      # Get slack list
      - lists:read
  1. Add the following user scopes
      - auditlogs:read #Only available on Slack Enterprise
      - admin.chat:read
      - admin.conversations:read
      - admin.usergroups:read
      - admin.users:read
      - admin.workflows:read

Step 3: Install the App and Retrieve the Token

  1. Install to Workspace: At the top of the OAuth & Permissions page, click Request to Install. You should see that button turn gray and say Request Submitted
  2. Authorize the App: Review the permissions and click Allow.
  3. Copy the Token: After installation, the page will display the Bot User OAuth Token. Copy this value, which begins with xoxb-.

Optional: Use an App-Level Token for Organization-Wide Ingestion

If your goal is to ingest messages from all channels (public and private) without needing to manually add the bot to each one, you can use an App-Level Token.

How to Generate an App-Level Token

  1. Go to your app’s settings: https://api.slack.com/apps
  2. Select your app and open the Basic Information tab.
  3. Scroll to App-Level Tokens (under Your App Configuration Tokens).
  4. Click Generate Token and copy the generated value — it will begin with xapp-.
  5. Assign the required scope:
    scopes:
  - *:history

This allows the token to access message history across channels in the workspace.

Internal note: App-level tokens (xapp-) differ from bot/user tokens (xoxb-, xoxp-). They grant workspace-wide API access, so use them carefully and store securely.

Step 4: Add bot to conversations needed for ingestion

For each channel that you want the bot added to, click on the channel name at the top of the channel view. This will open a new box that includes adding members, the channel settings, and the channel integrations.

  1. Click on Integrations.
  2. Click on Add an App.
  3. Find the Parable app that was made in previous steps and click Add

Enterprise Grid Installations vs Workspace Installations

If you’re working with Slack Enterprise Grid, understanding the difference between enterprise-level and workspace-level installations is critical for proper API usage and avoiding common errors.

What is the Difference?

Workspace Installation

  • The app is installed on a single Slack workspace
  • The API tokens (xoxb- for bot, xoxp- for user) are scoped to that specific workspace
  • API calls are inherently scoped to the workspace where the app was installed
  • The team_id parameter in API requests is optional and will be ignored if provided

Enterprise Installation (Org-Wide)

  • The app is installed at the organization level across an entire Enterprise Grid
  • The installation does not automatically grant access to any workspaces
  • An Org Admin must explicitly add the app to each desired workspace after installation
  • API tokens can represent permissions across multiple workspaces
  • The team_id parameter is required for most API methods to specify which workspace you’re targeting

API Token Behavior with Enterprise Installations

When you install an app at the enterprise level, the resulting tokens (both bot and user tokens) have different behavior:

Enterprise-Level User Token (xoxp-)

  • Can potentially access multiple workspaces within the organization
  • Must include team_id parameter in API requests to specify the target workspace
  • Even if the token is returned with a team_id during OAuth, that doesn’t mean the app has access to that workspace
  • Access must be explicitly granted by adding the app to each workspace

Key Point: A user token obtained from an enterprise installation may include a team_id in the OAuth response, but this does not guarantee that the app has been granted access to that specific workspace.

Common Error: team_access_not_granted

This is the most common error when working with Enterprise Grid installations, particularly with user tokens.

When This Error Occurs

When you attempt to make an API call (such as conversations.list or conversations.history) using an enterprise-level user token with a team_id parameter, you’ll receive:

{
  "ok": false,
  "error": "team_access_not_granted"
}

Why This Happens

  1. The app was installed at the organization level
  2. The user authenticated and granted permissions, providing a token with a team_id
  3. However, the app was never added to that specific workspace by an Org Admin
  4. Without explicit workspace access, the API call fails even though the token appears valid

How to Fix It

Option 1: Add the App to the Workspace (Recommended)

  1. Log in as an Org Admin for the Enterprise Grid
  2. Navigate to the admin dashboard at https://[your-org].enterprise.slack.com/admin/apps
  3. Find your app in the approved apps list
  4. Click on the app and select Add to workspaces
  5. Choose the specific workspace(s) where you need access
  6. Confirm the addition

Option 2: Use Workspace-Specific Installation If you only need access to specific workspaces and don’t require org-wide functionality:

  1. Install the app directly at the workspace level instead of enterprise level
  2. This generates workspace-scoped tokens that don’t require team_id parameters
  3. Simpler setup, but requires separate installation per workspace

Best Practices for Enterprise Grid Installations

  1. Always Include team_id: When using enterprise-level tokens, always provide the team_id parameter

  2. Verify Workspace Access First: Before making API calls, verify that the app has been added to the target workspace by checking:

    • The admin dashboard showing which workspaces have the app installed
    • Or attempting a simple API call like team.info with the team_id

  3. Handle Errors Gracefully: Implement proper error handling for team_access_not_granted errors:

    If error is "team_access_not_granted":
  - Prompt the user to contact their Org Admin
  - Provide instructions on adding the app to the workspace
  - Log which team_id was attempted for troubleshooting

  4. Document Token Type: Keep track of whether your tokens are from enterprise or workspace installations, as they behave differently

  5. Scope Verification: When requesting user scopes like admin.* scopes, these are typically only available with Enterprise Grid and require proper org-level permissions

Understanding team_id in Different Contexts

The team_id value appears in multiple places and can be confusing:

  • OAuth Response: When a user authorizes your app, the response includes a team_id - this is the workspace where the user authenticated
  • Enterprise ID: In Enterprise Grid, there’s also an enterprise_id representing the entire organization
  • API Requests: For enterprise tokens, you must provide team_id to specify which workspace within the organization you’re targeting

Critical Note: Just because a team_id is returned during OAuth doesn’t mean your app has access to that workspace. Access must be explicitly granted by an Org Admin through the admin dashboard.

Checking Your Installation Type

To determine if you’re dealing with an enterprise or workspace installation:

  1. Check the OAuth response - if it includes an enterprise_id field, it’s an enterprise installation
  2. Look at your app’s installation page in the Slack admin dashboard
  3. Test an API call with and without team_id - workspace tokens ignore it, enterprise tokens require it