> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Slack in production

> Set up and operate the Slack Gateway: one Slack app for every deployment, install, environment variables, drift detection, the delivery ledger, /forge commands and failures.

This page is for operators standing up Slack as an interaction surface for Forge. The end goal is: a single Slack app driving every Forge deployment, with approvals, slash commands, and Block Kit interactions routing to the right database.

## How the Slack gateway works

A single Slack app drives every Forge deployment. Slash commands, button clicks, modal submissions and events all land at one deployment — the **primary** — which verifies Slack's signature, works out which deployment owns the workflow, and relays the request there over a signed internal channel. Staging, preview and replica deployments never need their own Slack-facing URLs.

* **The routing host travels with the message.** Every button Forge posts carries the identifier of the deployment that owns it, and every modal carries it in its metadata. Because Slack signs the whole payload, a tampered routing host fails Slack's signature check.
* **Slack is answered first.** The primary acknowledges Slack within Slack's 3-second budget, then relays. The target deployment checks the relay signature, ignores duplicates, runs the handler, and updates the Slack message.
* **A relay is bound to its target.** Each relay is signed for one specific deployment, so it cannot be replayed against another.
* **A failed relay tells the user.** If the primary cannot reach the owning deployment, the person who clicked sees *"Forge couldn't reach the deployment that owns this workflow."*
* **Slash commands run on the primary.** A slash command carries no workflow context, so `/forge` always runs against the primary deployment's data.

### Resolution on any surface

The same approval can be shown in Slack and in the Forge Console at once, and either can resolve it. Forge records every place it presented a prompt; when someone resolves it anywhere, it updates or withdraws every other presentation. The resolved message names the surface — *"Resolved on Slack — 3 min ago"* or *"Resolved on Console"* — and the approval record stores the same value. A Slack-side cleanup failure never undoes the resolution in Forge.

### Delivery truth

Outbound Slack writes go through a durable outbox. Explicit Slack rate-limit and server errors can retry with recorded evidence. A timeout or lost connection after sending is recorded as `unknown`, not replayed, because Slack may have received the request. Files are stored as Forge files and attached only at send time.

## Capability ownership and installation identity

Slack is a provider for Forge capabilities; it is not a parallel application layer. The
provider can serve **notifications**, **human interaction**, **chat syndication**, **publish**,
and **org structure**. Slack-specific ingress interprets and verifies Slack payloads, then hands
typed requests to the owning capability. Only that capability's consumer mutates Forge domain
state. This keeps workflow decisions, chat state, governance, and worker identity vendor-neutral.

Each installed workspace is identified by the pair `(connectionId, slackTeamId)`. Runtime calls
resolve the installation's exact `credentialId`; credentials must target `slack/bot` and
carry the same org-unit scope as the connection. Resolution fails closed when the installation is
missing, ambiguous, inactive, unhealthy, revoked, expired, or scoped incorrectly. A token is never
selected merely because it belongs to the same organization.

The workspace install creates **one Forge Credential** targeting `slack/bot`, scoped to the org unit
that owns the installation (for example, Gloo LLC), and links its ID to the workspace connection.
That credential is the shared runtime credential for every Slack-backed capability: notifications,
human interaction, chat syndication, publish, and org structure. Forge does not mint a separate
credential per capability, and the providers do not read a parallel Slack token store or deployment
environment fallback. The org scope is the authorization boundary; it does not restrict the
credential to a single capability.

The Forge Console workspace-connection view exposes this installation identity and health state so
operators can diagnose routing without inspecting secrets. Ordinary outbound writes are placed in
the durable delivery outbox. A visible `unknown` result means Slack may have received the request:
verify Slack first, then reconcile it with an operator note rather than replaying automatically.
The native-agent flag is per connection and disabled by default.

## What you are setting up

One Slack app. One **primary** Convex deployment that owns the Slack-facing URLs. Zero or more **target** deployments (staging, preview environments, production replicas) that participate in the relay through HMAC-signed internal endpoints.

Operators have two responsibilities on every environment: configure environment variables, and — for non-primary deployments — register a row on the primary's deployment registry so the relay knows where to reach you.

## Install — first-time setup

1. **Create the Slack app.** In your Slack workspace, create a Forge Slack app. Configure interactivity URL `https://<primary-convex-site>/slack/interactions`, slash-command URL `https://<primary-convex-site>/slack/commands`, events URL `https://<primary-convex-site>/slack/events`, and OAuth redirect URI `https://<primary-convex-site>/oauth/slack/callback`. The four URLs all live on the **primary** Convex deployment — no per-environment URLs.

2. **Set primary-only env vars** in the Convex dashboard for the primary deployment: `SLACK_SIGNING_SECRET`, `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET`, `SLACK_OAUTH_STATE_SECRET` (generate a fresh secret — 32 bytes hex is fine), `SLACK_OAUTH_REDIRECT_URI` (must match the Slack app config exactly), `CONSOLE_BASE_URL` (the Forge Console origin).

3. **Set shared env vars on every deployment that participates in the relay**: `FORGE_RELAY_HMAC_SECRET` (one secret, identical on every deployment) and `FORGE_DEPLOYMENT_ID` (a unique slug per deployment: `primary`, `staging`, `pr-1234`, etc).

4. **Install the app per Slack workspace.** From the Forge Console, navigate to **Platform → Capabilities → Providers → Slack**, then click *Connect another workspace*. The browser redirects to Slack, the user authorizes the install, and Slack redirects back to the OAuth callback. The callback creates the org-scoped `slack/bot` Forge Credential, publishes the workspace connection only after that credential is linked successfully, and immediately schedules the workspace's org-structure sync. A new install no longer waits for the daily 06:00 UTC sync.

5. **Register target deployments on the primary.** For every non-primary deployment that needs to receive relayed traffic, add a row to the primary's `slackDeploymentRegistry` table: `{ deploymentId: "staging", url: "https://forge-staging.convex.site", enabled: true }`. Writing a registry row requires `platform:manage`.

> [!TIP]
>
> **Verify the install end-to-end.** After install completes, use **Verify workspace**, then **Send test DM to me**, under Platform → Capabilities → Providers → Slack. Next, post a real test approval through Forge. The DM and approval should appear in Slack, the Approve / Reject buttons should resolve cleanly, and `/observe` should show the corresponding `slack_gateway` events in the unified timeline.

## Slack app URLs

Configure these on the Slack app. All of them point at the **primary** deployment.

| Slack app setting | URL |
| - | - |
| Interactivity request URL | `https://<primary-convex-site>/slack/interactions` |
| Slash command request URL | `https://<primary-convex-site>/slack/commands` |
| Event subscriptions request URL | `https://<primary-convex-site>/slack/events` |
| OAuth redirect URL | `https://<primary-convex-site>/oauth/slack/callback` |
| Options load URL (run picker above 100 workflows) | `https://<primary-convex-site>/slack/options-load` |

Each route verifies Slack's request signature with a 5-minute replay window and answers `401` on failure, or `500` if `SLACK_SIGNING_SECRET` is not set.

## Environment variables

Set these in the deployment's environment settings, not in `.env` files.

| Variable | Where | Required | Notes |
| - | - | - | - |
| `SLACK_SIGNING_SECRET` | Primary | Yes | Slack-issued secret used to verify inbound requests. |
| `SLACK_CLIENT_ID` / `SLACK_CLIENT_SECRET` | Primary | Yes, for install | Slack app credentials for the install token exchange. |
| `SLACK_OAUTH_STATE_SECRET` | Primary | Yes, for install | Signs the install `state` token. |
| `SLACK_OAUTH_REDIRECT_URI` | Primary | Yes, for install | Must match the Slack app's redirect URL exactly. |
| `CONSOLE_BASE_URL` | Primary | Yes, for install | Where the install callback returns the browser. |
| `FORGE_RELAY_HMAC_SECRET` | Every relay deployment | Yes, for relay | One shared secret; must be identical everywhere. |
| `FORGE_DEPLOYMENT_ID` | Every relay deployment | Recommended | Unique slug per deployment. Defaults to `primary`. |
| `FORGE_RELAY_DISABLED` | Primary | Optional | `true` makes the primary handle every request itself — an emergency switch. |
| `SLACK_RELAY_REJECT_SAMPLE_RATE` | Every deployment | Optional | Records 1 in N rejected relay requests; default `10`. Use `1` while debugging and `100` during an attack. |
| `SLACK_AUDIT_RETENTION_DAYS` | Primary | Optional | Retention for relay and outbound audit rows; default 30 days. |
| `SLACK_DEFAULT_CHANNEL` | Primary | Optional | Where human task cards and workflow launches post when they have no channel of their own. Operator alerts never post here. |
| `SLACK_ALERTS_CHANNEL` | Primary | Optional | Channel for operator alerts (budget, secret rotation, lifecycle, runtime) and unthreaded escalations. Unset, those alerts are not posted to Slack. |

## Multi-environment routing

Once primary and targets are wired, the routing decision is automatic and embedded in every Block Kit payload.

When the workforce composes a Slack message from a workflow running on `staging`, every button's `action.value` carries `staging` as field 0. When the user clicks the button, Slack POSTs to the primary, the primary extracts `staging` from the payload, looks up the registry row, signs an envelope with `FORGE_RELAY_HMAC_SECRET`, and POSTs it to `https://forge-staging.convex.site/internal/slack-relay`. Staging verifies the HMAC, dedupes on the idempotency key, runs the handler, and updates the Slack message via `chat.update`.

The operator does not need to teach Slack about each environment. The routing host is metadata on every outbound presentation, and the registry on primary is the only mapping that needs to stay in sync.

## Direct messages

Notifications and approvals can reach a specific **person** rather than a shared channel. When a notification or an approval is addressed to a worker, Forge resolves that worker's linked Slack identity and delivers the message as a direct message — a 1:1 DM for a single recipient, or a group DM (Slack `mpim`, 2–8 recipients) when several workers are addressed at once.

Delivery is worker-native: the addressing is by Forge worker, and the Slack user is resolved through the worker's identity claim. If a worker has no linked Slack identity — or has turned DMs off — the platform falls back to the configured channel and @-mentions the intended recipients there, so a message is never silently dropped.

Two operator-relevant controls:

* **Per-worker opt-out.** Each worker can disable Slack DMs from the **My Work** settings. When a worker opts out, delivery to that worker cascades to the channel fallback. For a group DM, the all-or-nothing gate applies: if any addressed worker is unresolved or opted out, the whole audience cascades to the channel rather than delivering a partial DM.
* **Per-user Slack channel preference.** Independently of the worker-level opt-out, a user who sets **Slack off** in their notification-channel preferences is dropped from DM audiences — the gate reads the same `channels.slack` preference the email fanout reads. The gate is *fail-safe*: a user with no linked account, no preference row, or an unresolvable identity is treated as opted **in** (delivery proceeds), so a preference lookup can never silently suppress a message. Each drop is recorded in the outbound delivery ledger with outcome `skipped_pref`.
* **Scopes require a reconnect.** DMs use the Slack `im:write` and `mpim:write` scopes. A workspace connected before DM support was added will not have them. Reconnect the Slack app from **Platform → Capabilities → Providers → Slack** to grant the new scopes; until then, DM-addressed messages cascade to the channel fallback.

> [!TIP]
>
> **Confirm DM delivery.** Platform → Capabilities → Providers → Slack includes **Sync Slack users**, **Verify workspace**, and **Send test DM to me**. Sync first if the operator is not mapped, verify the connection, then send the DM. Forge resolves your Slack identity claim for the exact installed workspace; a claim for another Slack workspace is never selected as a fallback. A failed `conversations.open` displays Slack's error code and request ID for support escalation.

## Credential verification and lifecycle

The Slack row under **Platform → Vendors → Slack** is intentionally labeled **Slack OAuth
managed**. It represents the same Forge Credential created by the workspace install. Operators do
not paste, edit, or rotate its token on the Vendor page; use **Manage Slack workspaces** to return to
the Slack provider page. The row also exposes the shared credential system's **Verify now** control.
It resolves that exact credential and calls Slack `auth.test`; it does not create or consult a
second Slack credential store.

**Verify workspace** is the deeper installation check. It resolves the credential by the connection's
exact `credentialId` and org scope, calls Slack `auth.test`, and requires Slack to return both the
stored workspace ID and stored bot user ID. A valid token for a different workspace or bot fails
closed. The result updates the workspace lifecycle and health shown in the Console.

**Sync Slack users** runs the canonical `org_structure/slack` capability for that exact workspace.
The row shows the completion time plus matched and unmapped counts, and names the recovery action
when the sync fails. The daily 06:00 UTC sync remains a repair backstop.

Verify returns a `status` of `healthy`, `degraded` or `down`, and the workspace row's health label
changes to match:

| Health label | Verify `status` | Meaning | Operator action |
| - | - | - | - |
| `Verified` | `healthy` | The linked Forge Credential is live, Slack `auth.test` returned the stored workspace and bot, and no required scope is missing. | Send a test DM or continue normal operation. |
| `Active` | (no check yet) | The installation is active and has not been verified since it was connected. | Run Verify. |
| `Degraded` | `degraded` | Required scopes drifted. The reason names the missing scopes. | Reconnect Slack to grant them. |
| `Degraded` | `down` | A recoverable check failed: Slack was unreachable, `auth.test` returned a temporary error, or the credential cannot be used yet (for example, it is waiting for approval in Trust Fabric). | Fix the named reason and run Verify again; reconnect if it persists. |
| `Reconnect required` | `down` | Slack rejected the credential permanently, the credential link is invalid, or the workspace or bot identity did not match. | Reconnect the workspace to mint and link a new credential generation. |
| `Verification failed` | (earlier check) | The installation is active, but its last recorded health check failed. | Run Verify. |
| `Expired`, `Revoked` | (credential lifecycle) | The authorization expired, or Slack revoked it. Verify reports `down` for a revoked connection. | Reconnect Slack. |

The following results come from **Send test DM**, not from Verify:

| Result | Meaning | Operator action |
| - | - | - |
| `inactive` on test DM | The installation is not currently operational. | Run Verify and use the displayed lifecycle reason; reconnect if required. |
| `opted_out` on test DM | The worker-level Slack DM setting or the user's Slack notification-channel preference disabled DMs. | Enable both settings, then retry. |
| `unmapped` on test DM | Forge cannot find a Slack identity claim for your worker in this exact workspace. | Run Org Structure sync or repair the worker's Slack identity link. |

Non-expiring Slack bot tokens have no refresh token and must not enter refresh-token rotation. The
deployment initializer repairs only the historical, narrowly identified
`reinstall_required / refresh_token_missing` state produced by the former selector bug; it does not
reactivate other failed, expired, or revoked credentials.

## Drift detection

A cron on the primary fans out `/internal/whoami` pings to every enabled registry row. The whoami response carries the target's `deploymentId`, its current git SHA, and a structured `slackTokenStatus` (`ok` / `missing` / `malformed`).

Three outcomes are recorded inline on the registry row:

| Status | Meaning | Operator action |
| - | - | - |
| `ok` | Target returned its own `deploymentId` and a 200. | None. |
| `mismatch` | Target returned a *different* `deploymentId`. Two deployments are probably claiming the same slug, or a URL points at the wrong environment. | Audit the `FORGE_DEPLOYMENT_ID` env var on every deployment that could match. |
| `unreachable` | Request timed out or failed at the network layer. `lastWhoAmIError` carries the category: `timeout`, `dns_error`, `tls_error`, `http_<status>`, `shape_mismatch`, `wrong_deployment_id`, or `network_error: <detail>`. | Use the error category to localize — DNS / TLS errors mean an infrastructure issue; HTTP non-2xx means the target is up but the route isn't mounted; shape mismatch means a stale deployment. |

After **three consecutive failures**, the registry row's `enabled` flag flips to `false` and the primary stops dispatching to that target. Re-enabling is an operator action — set `enabled = true` once you have confirmed the target is healthy and `whoami` returns `ok`. Auto-recovery is intentionally not wired; a flapping target should be silent until an operator vouches for it.

## Outbound delivery ledger

Every outbound Slack send now leaves a row in the `slackSendAudit` ledger — the outbound mirror of the inbound relay audit. Before, a failed send was visible only as a `console.error` in the Convex logs; now each attempt records its surface, target channel, outcome, and (on success) the Slack message timestamp. The ledger never stores message content.

Nine surfaces are instrumented: ops alerts, run-threaded posts, notification DMs, human-interaction prompts, agent publish (body + per-file upload), chat syndication, simple messages, and App Home publishes. Each row's `outcome` is one of:

| Outcome | Meaning |
| - | - |
| `attempt` | Recorded before the send; the outcome was never written (the send may or may not have reached Slack). |
| `sent` | Delivered; `messageTs` holds the Slack timestamp. |
| `fallback_text` | Block payload failed validation or a file upload lost `files:write`; delivered as text / a link instead of being dropped. |
| `failed` | Slack returned an error; `error` holds the code (e.g. `channel_not_found`). |
| `skipped_no_credential` | No Slack bot token resolved for the scope. |
| `skipped_no_channel` | No channel to post to: an operator alert with no `SLACK_ALERTS_CHANNEL` (it never falls back to `SLACK_DEFAULT_CHANNEL`, where people are asked; an event with a bell still shows in the Console), or another send with no channel. |
| `skipped_pref` | A user's `channels.slack` preference dropped the DM. |
| `skipped_rule` | A syndication relay was suppressed by its outbound rule. |

A send that will deliver is recorded first, as an `attempt` row; if that row cannot be written, the send does not happen. The row is then updated with the outcome. A skipped send is recorded after the fact and never blocks anything, because nothing is delivered. Rows are rotated by the same *slack gateway audit retention* cron as the relay audit, on the `SLACK_AUDIT_RETENTION_DAYS` horizon (default 30 days).

## Alert Slack sink

Observability alert rules (**Observe → Alerts**) can deliver to Slack. When creating a rule, choose the **Slack** sink and enter a Slack **channel ID** (`Cxxxxxxx` for a public/private channel or `Gxxxxxxx` for a group) — the bot must be a member of that channel. A firing rule posts the alert title and match summary to that channel; the delivery is recorded in the outbound ledger like any other send.

> [!NOTE]
>
> **Channel ID, not name.** The sink targets a raw Slack channel ID, not a `#channel` name. Copy it from Slack (channel → *View channel details* → the ID at the bottom). The console validates the `C`/`G` prefix format before saving.

## App Home

Opening the Forge app's **Home** tab in Slack shows the signed-in user their actionable work without leaving Slack:

* **Waiting for you** — up to 10 open tasks that ask you, newest first: approvals, workflow steps, agent setup requests, and questions an agent asked you. Each is drawn from its form. When the form can be answered in Slack, Home shows its buttons (or a select, or a short reason dialog); otherwise it shows one **Open in Forge** link (an agent question opens in **My Work**). The buttons carry the same action encoding as the task's prompt, so the same authorization gate applies: a click is governed identically whether it comes from a channel prompt, a DM, or Home. Platform review tasks (synthesis requests, held procedure drafts, judge admissions and curator recommendations) are not listed here or in `/forge approvals`; they are in **My Work**.
* **Running workflows** — the workflows the user has triggered (console/API dispatches), with status and start time.
* **Run a workflow** — opens the workflow picker modal, and a link into the Forge Console.

An unmapped Slack user (no linked Forge worker) sees a short "link your account" message instead. App Home requires the **App Home** tab and the `app_home_opened` event subscription to be enabled in the Slack app configuration — no new OAuth scope.

## The `/forge` slash vocabulary

Beyond `run <workflow>` and the bare picker, the slash command understands three read-only sub-commands. All require a mapped Forge worker but **not** `workflows:use`:

| Command | Result |
| - | - |
| `help` | Lists the available commands (ephemeral). |
| `status` | Your running workflows — name, status, start time, and a link into the Console. |
| `approvals` | Your pending approvals, each with Approve / Reject buttons (same governed encoding as App Home). |

## Launching a workflow from Slack

`/forge` with no text opens a picker; `/forge run <name>` dispatches directly.
Both compose from the workflow's canonical input contract, so what Slack asks
for matches what the Console asks for — parameters only.

**Typed widgets.** A `month` parameter renders a generated rolling ±12-month
select with the current month suggested; `date` renders Slack's date picker
(which can only emit `YYYY-MM-DD`, so a malformed date is unreachable);
`number` and `integer` render a numeric input Slack validates before submit; a
short enum renders as radio buttons and a longer one as a dropdown; a
`string[]` with an enum renders as checkboxes. Dispatch validation performs no
coercion, so each of these removes a class of rejection the operator would
otherwise discover only after pressing Run.

**Pre-filled — for authorized users.** Block Kit has no client-side evaluation,
so the seed priority runs server-side when the modal is composed: the last
completed production run → the parameter's `defaultExpr` → its static default.
The monthly close opens with last month already selected.

Those seeds are prior-run *data* — argument values, and a bound asset's
filename — not contract metadata, so they are gated on a real `workflows:use`
check even when the inbound authorization posture is temporarily set to `warn`.
The posture governs whether an unauthorized *action* is blocked; it does not
govern who sees data. A workspace
member without `workflows:use` still gets the full contract from the picker,
blank. If your operators report the modal opening empty, check their
`workflows:use` grant before suspecting the seed logic.

**Derived and bound inputs are shown, not asked.** Computed values appear as
context lines under the form (`acumaticaPeriods = ["052026"]`), and a bound
asset shows its current file and when it changed. Neither is editable from
Slack — an asset is `workflows:manage` configuration and a launch surface must
not override it.

**Large registries.** Above 100 workflows the picker switches from a static
dropdown (which Slack silently truncates at 100) to a type-ahead
`external_select`. That requires an **Options Load URL** in the Slack app
config pointed at `https://<deployment>.convex.site/slack/options-load`. Set it
during install; without it the type-ahead returns an empty menu.

### Zero-tap launch (feature-flagged, default OFF)

With the `slack.zero-tap-launch` feature flag enabled, `/forge run <name>` posts
a **confirm card** instead of dispatching immediately, whenever every required
parameter resolves: the parameter values, the derived expansion, the asset
binding, a Console deep link, and `[Launch] [Adjust…] [Cancel]`. Launch
dispatches exactly what the card displayed; Adjust opens the pre-filled modal;
Cancel rewrites the card. A double-tap starts one run.

> [!WARNING]
>
> **Release gate.** The flag is seeded **off** as a reversible product rollout control. Slack
> authorization is independent: Slack inbound authorization always enforces, so a
> Slack user without the required permission is denied and the decision is
> audited. Before enabling zero-tap launch, review the 30-day grant audit on the
> Slack provider surface.

## When Forge refuses

A refusal in Slack or email says what happened in a sentence. It never shows a
code, an internal id, or a status. Examples are a Slack command run without the
permission, an approval you can't release, or a direct message from an account
not linked to a Forge person.

When Forge recorded a decision for the refusal, the reply ends with
`Reference: <id>.`. Give that reference to an administrator, who can find the
decision it names in the Trust Fabric decision log. The reply has no Console
link, because the decisions page does not open a recorded denial for the person
refused.

## Where to look in the Forge Console

Four surfaces hold the operator-visible signal for the gateway.

**Observe → Events** (`/observe`). Filter to the `slack_gateway` category to see relay decisions in the unified timeline. Each event carries the decision, outcome, host, action id, and `payloadDigest`. Use the digest to correlate a primary-side row with the target-side audit on the other end.

**Platform → Schedules** (`/platform/schedules`). Three Slack-gateway crons run on the primary: *slack gateway audit retention* (deletes both the relay audit and the outbound `slackSendAudit` ledger rows older than `SLACK_AUDIT_RETENTION_DAYS`, default 30 days), *slack gateway idempotency gc* (evicts dedup rows past their 5-minute TTL), *slack gateway drift detection* (the whoami fan-out described above). Watch their last-run statuses here.

**Platform → Capabilities → Notifications** (`/platform/capabilities/notifications`). The **Recent Slack sends** card renders the outbound delivery ledger described above — time, surface, event type, channel, and a color-coded outcome badge, with an error tooltip and a per-surface filter. This is the fastest way to answer *"did that alert / approval / publish actually reach Slack, and if not, why."* Reading it requires the `audit:read` permission.

**Trust Fabric → Decisions** (`/trust-fabric/decisions`). The append-only compliance view. Every approval that resolved through Slack carries `actorIdentity.kind: "slack"` and the `payloadDigest` that links to the primary's audit row. Use this when the question is *"who actually approved this, on what surface, and can I prove it."*

**Platform → Capabilities → Providers → Slack** (`/platform/capabilities/providers/slack`). Workspace install management. It lists connected workspaces, scopes, install timestamps, linked credential health, **Verify workspace**, **Send test DM to me**, reconnect, and disconnect controls. The workspace list and its delivery-problem list read the workspaces homed at exactly the org unit the page names (workspaces homed at its descendants are not listed), then keep only those whose org unit is inside your scope closure: a platform-scope role grant keeps them all, and an org-unit grant keeps them only when the named unit is that unit or under it.

## Common failure modes

The set below covers the recurring issues. For each, the symptom names what the operator sees, and the resolution names the env var or registry row to check first.

**Slack returns "your Slack account isn't linked to a Forge worker yet."** An operator with no Forge worker tried to use the gateway. Resolution: invite the user as a worker on the relevant org unit. The unmapped attempt is recorded in `unmappedIdentityAttempts` for admin triage.

**A button click produces the ephemeral "Forge couldn't reach the deployment that owns this workflow."** The primary couldn't relay to the target. Check `slackRelayAudit` for the matching row — `decision` will be `target_unknown` (no registry row), `secret_missing` (`FORGE_RELAY_HMAC_SECRET` not configured), `self_relay_refused` (registry URL points at primary), or `relayed` with `outcome=target_failed` (network or HMAC issue on the target).

**OAuth install lands on the Console with `?error=<reason>`.** The install callback returns to the Slack provider page with a reason:

| Reason | Meaning |
| - | - |
| `missing_params` | Slack's callback had no `code` or `state`. |
| A state-verification reason | The install `state` token was forged, expired or replayed. Restart the install. |
| A Slack error, such as `access_denied` or `invalid_code` | Slack refused the token exchange or the user cancelled. |
| `missing_team_or_bot` | Slack answered without a workspace or bot user ID. |
| `upsert_failed` | The token exchange succeeded but saving the install failed. The single-use code is spent, so restart the install, and check the deployment logs at that time. |

**Drift detection auto-disables a registry row.** Three consecutive `/internal/whoami` failures. Inspect `lastWhoAmIError` for the category: `timeout` / `dns_error` / `tls_error` point at infrastructure; `http_<status>` means the target is up but the route isn't mounted (verify the gateway code is deployed); `shape_mismatch` or `wrong_deployment_id` mean a stale or misconfigured target. Re-enable manually once healthy.

**Inbound rejection rate spikes.** `slackRelayAuditFallback` shows a burst of `bad_signature` or `replay_window_exceeded` rows. The reject path is sampled 1-in-10 by default — actual rejection volume is 10× what you see in the audit. If this is an attack, raise `SLACK_RELAY_REJECT_SAMPLE_RATE` to 100 to further reduce database volume; the structured log lines still alert on volume even when sampled out.

**Audit rows label a relay `legacy_fallback`.** A composer somewhere is still emitting pre-gateway button shapes (no host prefix). The legacy fallback routes to the primary, so behavior is correct, but the signal means a message composer still needs migrating; report it to the Forge team.

## Do it over the API

These calls use the `FORGE_BASE` set up in the Raw HTTP tab of the [quickstart](https://docs.gloo.com/forge/quickstart.md). These operations refuse an External App token: send a [Personal key](https://docs.gloo.com/forge/console/settings/personal-keys.md#choose-a-credential) or a platform API key as the bearer instead of the quickstart's `ACCESS_TOKEN`, with scopes that include `connections:manage` and `audit:read`. The install, environment variables and registry rows are set up as described above; these calls verify a connected workspace and read the outbound delivery ledger.

List an org unit's connected workspaces:

```bash theme={null}
curl -sS "$FORGE_BASE/api/v3/connection-slack-workspaces?orgUnitId=$ORG_UNIT_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq '.data[] | {connectionId, slackTeamName, lifecycleStatus, lastHealthStatus}'
```

Verify one workspace's bot credential with Slack and record its health:

```bash theme={null}
curl -sS -X POST "$FORGE_BASE/api/v3/connection-slack-workspaces/$CONNECTION_ID/healthcheck" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: slack-healthcheck-$CONNECTION_ID-v1" \
  -d "{\"orgUnitId\": \"$ORG_UNIT_ID\"}" \
  | jq '.data'
```

Both need `connections:manage`. `data.status` is `healthy`, `degraded` or `down`, and `scopeDrift` lists scope differences. Read the most recent outbound sends, which needs `audit:read`:

```bash theme={null}
curl -sS "$FORGE_BASE/api/v3/notification-slack-sends?limit=25" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq '.data[] | {sentAt, surface, eventType, outcome}'
```

Over MCP, run the health check with `forge_call_operation`:

```json theme={null}
{
  "operationId": "healthcheckSlackWorkspaceAdmin",
  "input": { "connectionId": "<connection id>", "orgUnitId": "<org unit id>" },
  "idempotencyKey": "slack-healthcheck-<connection id>-v1"
}
```

and list workspaces with `forge_call_read_operation`:

```json theme={null}
{ "operationId": "listSlackWorkspacesAdmin", "input": { "orgUnitId": "<org unit id>" } }
```

## Related

* [Observability](https://docs.gloo.com/forge/run/observability.md)
* [Approvals & HITL](https://docs.gloo.com/forge/run/approvals-and-hitl.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.