CONNECT AN API · SLACK · 5 MINUTES

Connect Slack¶

Slack needs a bot token. You get one by creating a small Slack app in your own workspace, from a manifest we publish. The token goes straight into your Enclave's vault and never reaches EKKA.

You need to be able to add apps to your Slack workspace. In most workspaces that means being an admin, or having an admin approve it.

What you'll have at the end

A token in your Enclave's vault, a grant that says which agent may use it, and ekka api test slack showing four green checks against a real call to Slack.

Step 1 · Create the app¶

Open api.slack.com/apps and sign in, then grab the manifest so you have it ready:

Download the EKKA manifest

Click Create New App
Under Or start your own way, choose From a manifest
Click Continue
Select the YAML tab and paste the manifest over what is already there
Under Workspace, choose the workspace you want EKKA to post in
Click Next, review the summary, then Create
Slack asks you to approve the app. Click Allow

Steps 4 and 5 are the same screen, so paste the manifest and pick the workspace before clicking Next.

The workspace cannot be changed later

Slack says so on that screen. Picking the wrong one means creating the app again.

Slack then asks you to approve the app, showing exactly what it will be allowed to do. Click Allow.

That approval is the install. Because the manifest already carries its permissions, creating the app and installing it are one step, and there is nothing else to click.

It asks for four permissions and nothing else, one for each thing EKKA can do:

Permission	What it lets EKKA do
`chat:write`	post a message
`channels:read`	list channels
`channels:history`	read recent messages in a channel
`users:read`	list the people in the workspace

Step 2 · Copy the token¶

In the left sidebar, open OAuth & Permissions. At the top you will see Bot User OAuth Token, already issued, starting with xoxb-.

Click Copy.

If that page shows a Reinstall button rather than an install one, that is normal. The app is already installed, from step 1.

Treat it like a password

Anyone holding this token can act as the bot in your workspace. Do not paste it into a terminal command, a ticket, a chat message, or a screenshot. The next step reads it without showing it and without putting it in your shell history.

If a token is ever exposed, reinstalling does not replace it. Slack adds scopes to the token you already have, so an exposed token is ended by revoking it: remove the app from the workspace, or call auth.revoke with it. Then create the app again and reconnect.

Step 3 · Add the EKKA icon¶

The icon is what your team sees beside every message the agent posts. Slack does not accept an icon inside a manifest, so it is one upload.

Download the icon
Open Basic Information
Scroll to Display Information and upload it under App icon
Save Changes

You can make it yours

Change the name and icon here if you would rather it looked like your own tool. Nothing in EKKA depends on either.

Step 4 · Give it to your Enclave¶

ekka api connect slack

It prints what it is about to connect, then asks for the token with the input hidden. Paste it and press enter.

  Slack Web API (slack@1)
  Credential: A bot token. It starts with xoxb-.
Secret to store under 'API_CREDENTIAL_SLACK' (input hidden, press Enter when done):
  ✓ credential stored in this machine's vault
  ✓ connection written, pinned to slack@1

Step 5 · Let your agent use it¶

connect finishes by printing this, with your values already in it:

ekka gate grant add --type api --instance <your-api-gate> \
  --resource apis/slack --capability api.read --no-fingerprint

Run it. That grants reading. To let the agent post, run it again with --capability api.write.

Until you do this, nothing can call Slack. You choose which agent gets it, and you can take it back later without touching the connection.

Step 6 · Check it works¶

ekka api test slack

  ok       config      https://slack.com · bearer
  ok       credential  API_CREDENTIAL_SLACK is in the vault
  ok       grant       govern allows api.read on apis/slack
  ok       live call   GET /api/auth.test answered as expected

The live call row is a real call to Slack with your token. The verdict printed under the rows reads WORKING when all four passed, and the row that failed names what to fix when one does not.

Post your first message¶

Invite the bot to a channel first. In Slack, in that channel, type:

/invite @ekka

Then a plan step that posts:

{ "id": "post", "action_ref": "ekka.gate.api.v1",
  "target": "<your api gate>", "op": "send", "call": "postMessage",
  "inputs": { "resource": "apis/slack",
              "channel": "#ops", "text": "deploy finished" } }

ekka api spec slack lists every operation and what each one takes.

When something is refused¶

"not_in_channel". Invite the bot to that channel with /invite @ekka. For public channels you can instead add the chat:write.public permission in OAuth & Permissions and reinstall, which lets it post anywhere public without an invite.

"missing_scope". Slack names the permission it wanted. Add it in OAuth & Permissions, then click the Reinstall button on that page and approve again. Your token does not change: Slack adds the new permission to the token you already have, so there is nothing to reconnect. Just run ekka api test slack again.

Private channels need groups:read and groups:history added, a reinstall, and the bot invited to the channel. The manifest leaves them out, so you are not granting reach you never asked for.

A grant refusal is different from a Slack refusal, and ekka api test slack tells them apart: the grant row is EKKA saying no, the live call row is Slack saying no.

Turning it off¶

Removing the grant stops your agent using Slack, and keeps the connection:

ekka gate grant list
ekka gate grant revoke <id>

Removing everything from this machine, including the token:

ekka api disconnect slack

To cut it off at the Slack end, open the app's OAuth & Permissions page and revoke the token there. That kills it everywhere at once, no matter who holds a copy.