Tako AI ‐ Slack Bot Setup & Testing Guide - fctr-id/okta-ai-agent GitHub Wiki

This guide walks you through connecting TakoAI to your Slack workspace so your team can query Okta data directly from Slack using /tako.

What you'll need:

  • TakoAI already installed and running
  • Slack workspace admin permissions (to create and install apps)
  • About 15 minutes

Part 1 — Create your Slack App

1.1 Go to the Slack App Dashboard

Open https://api.slack.com/apps and click "Create New App".

Choose "From scratch", give it a name (e.g. TakoAI), select your workspace, then click Create App.

1.2 Add Bot Permissions

In the left sidebar, click OAuth & Permissions.

Scroll down to Bot Token Scopes and add these scopes one by one:

Scope Why it's needed
chat:write Post query results and status messages
files:write Upload CSV exports and generated scripts
commands Receive /tako slash commands
app_mentions:read Respond when users @mention the bot
users:read Look up user profiles for access control
users:read.email Read user email addresses for allowlisting
usergroups:read Check Slack group membership for allowlisting

After adding scopes, scroll up and click Install to Workspace → Allow.

Once installed, copy the Bot User OAuth Token — it starts with xoxb-. You'll need this shortly.

1.3 Copy the Signing Secret

In the left sidebar, click Basic Information.

Under App Credentials, copy the Signing Secret. This is used to verify that incoming requests genuinely come from Slack.

Part 2 — Configure the Slash Command

2.1 Create /tako

In the left sidebar, click Slash Commands → Create New Command.

Fill in:

Field Value
Command /tako
Request URL https://your-takoai-server.com/slack/events
Short Description Query Okta data with AI
Usage Hint [query | sync | status | history | favorites | help]

Replace your-takoai-server.com with the actual hostname or IP where TakoAI is running. If you're testing locally and your server isn't publicly accessible, see Part 3 (Socket Mode) before doing this step.

Click Save.

2.2 Enable App Mentions (optional)

If you want users to be able to @TakoAI how many active users are there? in channels:

  1. In the left sidebar, click Event Subscriptions
  2. Toggle Enable Events to ON
  3. Set Request URL to https://your-takoai-server.com/slack/events
    • Slack sends a verification challenge — your TakoAI server must already be running to pass this
  4. Under Subscribe to bot events, add app_mention
  5. Click Save Changes

Part 3 — Local / Private Server Setup (Socket Mode)

If TakoAI is running on a private network (your laptop, internal server without a public URL), use Socket Mode instead of a public URL. Socket Mode makes the Slack bot connect outbound to Slack via WebSocket — no need to expose any port.

  1. In the left sidebar, click Socket Mode
  2. Toggle it ON
  3. Give the token a name (anything, e.g. tako-socket) → Generate
  4. Copy the App-Level Token — it starts with xapp-

When using Socket Mode, the Request URL fields in the slash command and event subscription steps above don't matter — you can leave them blank or set them to any URL.

Part 4 — Configure TakoAI

Open your TakoAI .env file and add the following:

# ===================================================================
# SLACK BOT CONFIGURATION
# ===================================================================

# Set to true to enable the Slack bot
ENABLE_SLACK_BOT=true

# From Part 1.2 — starts with xoxb-
SLACK_BOT_TOKEN=xoxb-your-bot-token-here

# From Part 1.3 — the signing secret
SLACK_SIGNING_SECRET=your-signing-secret-here

# From Part 3 — only needed if using Socket Mode, starts with xapp-
SLACK_APP_TOKEN=xapp-your-app-token-here

# How Slack delivers events: "socket" (default, no public URL needed) or "http" (public server)
SLACK_OPERATION_MODE=socket


# ===================================================================
# ACCESS CONTROL (required — deny-by-default)
# ===================================================================
# The bot blocks ALL users unless you configure at least one option below.
# This is a safety measure — if you forget to set these, no one can query.

# Option A: Allow specific users by email (comma-separated)
[email protected],[email protected]

# Option B: Allow Slack User Groups by name (comma-separated)
# Use the group handle exactly as it appears in Slack (e.g. @okta-admins → "okta-admins")
SLACK_ALLOWED_GROUPS=okta-admins,it-admins

# Option C: Allow ALL workspace users — see warning below before enabling
# SLACK_ALLOW_ALL_USERS=false

⚠️ Security Warning — SLACK_ALLOW_ALL_USERS=true Setting this to true grants every user in your Slack workspace the ability to query your entire Okta tenant — users, groups, apps, and policies. Only enable this if your workspace is small, internal, and fully trusted. For production environments, use SLACK_ALLOWED_EMAILS or SLACK_ALLOWED_GROUPS instead.

How access control works:

  • Default: locked down. If SLACK_ALLOWED_EMAILS, SLACK_ALLOWED_GROUPS, and SLACK_ALLOW_ALL_USERS are all empty/false → the bot rejects every command
  • If either allowlist is set → a user is allowed if their email matches OR they are in any of the listed groups
  • SLACK_ALLOW_ALL_USERS=true → everyone in the workspace can use the bot (skips allowlist checks)
  • Users who are blocked see an ephemeral ":lock: You are not authorized" message — only they can see it

Changing access control requires a server restart. All settings are loaded once at startup. After editing .env, restart TakoAI (docker-compose restart or restart the server process) for changes to take effect.

Part 5 — Install Dependencies and Start the Server

5.1 Dependencies

Docker: No action needed — dependencies are bundled in the image.

Fresh install (git clone): No action needed — slack-bolt[async] is included in requirements.txt. Running pip install -r requirements.txt covers it.

Existing install (upgrading from an older version): Run this to add the new Slack packages:

pip install "slack-bolt[async]" slack-sdk

5.2 Start TakoAI

python main.py

Check the startup logs. You should see:

Socket Mode (SLACK_OPERATION_MODE=socket):

Slack bot routes enabled
Slack routes mounted: /slack/events, /slack/interactions
Slack Bolt app created successfully
Slack Socket Mode task started (SLACK_OPERATION_MODE=socket)

HTTP Mode (SLACK_OPERATION_MODE=http):

Slack bot routes enabled
Slack routes mounted: /slack/events, /slack/interactions
Slack Bolt app created successfully
Slack running in HTTP mode (SLACK_OPERATION_MODE=http) — ensure server has a public URL

If you configured group allowlisting, you'll also see something like:

Slack access control: allowed groups resolved: okta-admins (S0123ABCD), it-admins (S0456EFGH)

Part 6 — Invite the Bot to a Channel

The bot must be invited to a channel before it can post there.

In any Slack channel, type:

/invite @TakoAI

Slash commands (/tako) work in any channel without invitation. Mentions (@TakoAI) only work in channels the bot has been invited to.

Part 7 — Test It

Try these commands in Slack:

Check status

/tako status

Only you can see the response. Shows database health, last sync time, and how many users/groups/apps are synced. If it says "no data", run a sync first.

Sync Okta data

/tako sync

Triggers a full sync of your Okta data into the local database. Progress updates post to the channel every 10 seconds. Run this once before querying.

Run a query

/tako list all active users
/tako which apps use SAML?
/tako how many groups have more than 50 members?

View query history

/tako history

Shows your last 5 queries with ▶ Run and ☆ Star buttons. Only you can see it.

View favorites

/tako favorites

Shows your starred queries. Use ▶ Run to re-execute a saved query instantly — no AI processing needed.

Get help

/tako help

Troubleshooting

Problem What to check
/tako does nothing Server logs — ensure ENABLE_SLACK_BOT=true and bot token/signing secret are set
dispatch_failed error in Slack You're using SLACK_OPERATION_MODE=http but Slack can't reach your server. Switch to SLACK_OPERATION_MODE=socket for local/private servers.
"Processing..." never updates The server must be reachable from Slack. Use SLACK_OPERATION_MODE=socket for local servers.
":lock: You are not authorized" Your email isn't in SLACK_ALLOWED_EMAILS and you're not in any group in SLACK_ALLOWED_GROUPS. Add your email to SLACK_ALLOWED_EMAILS, or add your Slack group handle to SLACK_ALLOWED_GROUPS. Setting SLACK_ALLOW_ALL_USERS=true bypasses all checks but exposes full Okta data to the entire workspace — use only in trusted environments.
Everyone gets "not authorized" Access control is deny-by-default. You must set at least one of: SLACK_ALLOWED_EMAILS, SLACK_ALLOWED_GROUPS, or SLACK_ALLOW_ALL_USERS=true
Changed .env but nothing happened Restart required. Settings are loaded once at startup. Run docker-compose restart or restart the server process.
Group access not working Check that the group name in SLACK_ALLOWED_GROUPS exactly matches the Slack group handle. Check server logs for warnings. Also ensure usergroups:read scope is added.
"No synced data" warning on queries Run /tako sync first to populate the local database
Permission error uploading files Ensure the files:write scope is added and the app has been reinstalled after adding it
Scopes not taking effect After adding new scopes in the Slack dashboard, you must reinstall the app to the workspace for them to apply