Skip to main content
← Back to list
01Issue
FeatureShippedPlatformPublic
Assigneesskunk-ape

Relationships

#4619 Manual: build your own integration with swamp serve, using Slackwater as the reference

Opened by skunk-ape · 11/10/2026· Shipped 11/11/2026

Part of #4459, as item 15. Customers build and run their own Slack apps and other integrations. Slackwater is a reference to help them build one, and we don't host an app. Today the only way to learn how is to read Slackwater's code. Nothing in the manual explains the link contract, its refusals, or what an app must do that serve can't enforce.

Goal

A manual guide, in content/manual/, that takes a developer from nothing to a working integration that links people and acts for them through swamp serve, safely. It's written for someone who has never seen swamp's internals, in any language, using Slackwater as the worked example.

What it covers

  • The model: an integration acts for a person within a ceiling. Effective rights are the person's grants ∩ the integration's ceiling ∩ what they consented to. What the operator does, what the person does, and what the app holds.
  • Setting up, as an operator: registering an integration and its ceiling with swamp access integration, the integration credential, grants for people, deny conditions on the client and initiator (no self-approval, refusing an integration), --require-email-match, and which plans include links.
  • Linking a person: start, the consent URL (shown only to that person), polling redeem at the interval serve gives, storing tokens. What the person sees on the consent page and in the email, including #4607's "this account is mine" confirmation. The app should send the person's email when starting a link.
  • Acting for a person: the bearer-only action route, idempotencyKey per user action, a gate decision carrying suspendedAt, and a run bound to the delegation rather than the token.
  • Tokens: the 1-hour access token, refresh with the integration credential (it keeps the refresh token), the 30-day delegation that isn't extended, and relinking to consent again.
  • Every refusal an app must handle, and what to show the person: consent_required, refresh reasons (suspended, links_unavailable, not_admitted), ended links ("this wasn't me", an undeliverable email, leaving the collective, the collective's plan lapsing), rate limits, and swamp-club unreachable.
  • What serve can't enforce, so the app must:
    • store the integration credential and tokens as secrets;
    • bind tokens to the chat user who started the link, and never let one person's token act for another;
    • show the consent URL only to that person;
    • make idempotency keys from the user's action;
    • keep a ceiling narrow, naming workflows rather than using wildcards, because run also allows cancelling any run of that workflow;
    • never log tokens.
  • Known limits, stated plainly: a compromised app can act for its linked people within the ceiling until it's revoked; work already started outlives a link; signal payloads continue a run with its starter's access; links end within about 30 seconds, not at once.
  • Slackwater as the reference: a walk through its link, run and approve paths, which module to port to another language, and running it beside serve in Socket Mode.

Serve manual corrections (moved from #4554)

The guide's PR also brings the existing serve manual up to date, since it edits those pages anyway:

  • content/manual/how-to/swamp-serve/deploy-headless-oauth.md, "Respond to a leaked client secret", step 3: replace the paragraph that opens "The server does not yet learn that swamp-club ended the links" with "Serve refuses these links on its own within about 30 seconds and ends them once it reads swamp-club again. To end them at once, revoke each integration on the server:". Keep the two commands that follow. This came from #4589.
  • set-up-oauth-auth.md: say a serve set up through the browser device approval can't link people (link starts answer 409 links_require_collective_client, since #4626), and point to "Deploy with Headless OAuth" for a serve that will.
  • Check the serve manual's link, rotation and host-compromise pages against what shipped in #4563, #4584, #4607, #4608, #4609, #4610, #4622, #4623 and #4626, and fix anything stale. List what changed in the PR.

Not in scope

The Slackwater repo's own README, a hosted app, and swamp-lib's TypeScript API reference beyond a pointer.

Done when

  • The guide is in the manual and linked from the serve section.
  • A developer can follow it to link a person and run and approve a gated workflow as them, against a local serve and swamp-club. This is checked by following it from a clean machine, in a language other than TypeScript for the HTTP calls (curl is enough).
  • Every refusal serve and swamp-club can return to an app is listed with what to do.
  • The serve manual corrections above are made.
  • It matches what shipped. Each claim about behaviour is checked against the code on main.
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 5 MOREREVIEW+ 7 MOREPR_MERGED+ 2 MORESESSION_SUMMARIZED

Shipped

11/11/2026, 7:10:35 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
skunk-ape assigned skunk-ape11/10/2026, 10:23:31 PM

Sign in to post a ripple.