Skip to main content
← Back to list
01Issue
FeatureShippedSwamp CLIPublic
Assigneesstack72

Relationships

#1863 docs(skill): serve guide's Token Management section is bare, leads to picking the wrong mint command

Opened by stack72 · 8/27/2026· Shipped 8/27/2026

Where

references/serve/guide.md in the shipped swamp skill (Claude Code / Claude Desktop). Current `## Token Management` section (see line ~180):

``` swamp access token mint --principal user: # plaintext stored in vault swamp access token list swamp access token revoke swamp access token rotate # revoke + mint replacement swamp access token rotate --vault # rotate into a different vault ```

Problem

The section lists commands but not the context an agent needs to pick the right one when configuring a headless client (a worker, a CI runner, a k8s Pod) to authenticate against `swamp serve` in `--auth-mode oauth`. Without that context the agent reaches for the top hit in `swamp help auth token`, which is `swamp auth token create --collective --scopes 'serve:*'`. That mints a swamp-club collective API token (raw `swamp_org_`, goes in `SWAMP_API_KEY`), not a server token (`.` format, goes in `SWAMP_SERVER_TOKEN`). Serve then rejects every WS handshake with:

``` WebSocket auth rejected for "ip:127.0.0.1" from "127.0.0.1": "Invalid token format: expected ." ```

I hit this in a live debugging session and burned time (and minted several test tokens I had to revoke) before finding `swamp access token mint` via a fan-out search of the full `swamp help` tree.

What the section should cover

  • The two token families, side by side, so an agent can pick correctly:

    • `swamp auth token create` → swamp-club collective API tokens. Format: raw `swamp_org_`. Env: `SWAMP_API_KEY`. Scopes: `serve:`, `oauth:manage`, `extensions:`, `datastore:*`. Used by `swamp serve` itself to talk to swamp-club (feature gates, OAuth client registration).
    • `swamp access token mint` → per-serve access tokens. Format: `.`. Env: `SWAMP_SERVER_TOKEN`. Principal: `user:`. Used by clients to authenticate against a specific `swamp serve` instance in `--auth-mode oauth` or `--auth-mode token`.

  • The wire-format error signature (`Invalid token format: expected .`) so the fix is one search away.

  • The reveal pattern for wiring the plaintext into an external secret store (Kubernetes Secret, 1Password, etc.) without letting it hit a terminal:

    ```bash swamp access token reveal --repo-dir /repo -y --json | jq -re .plaintext | ```

  • A note that `swamp access token mint` runs against a local repo/vault — for headless deployments targeting a remote serve, mint via `kubectl exec` (or equivalent) inside the serve process's own environment, not on the operator's laptop.

Happy to send a PR against the skill's canonical source if you point me at it.

Automoved by swampadmin from https://github.com/swamp-club/swamp/issues/2287

02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 2 MOREREVIEW+ 7 MOREPR_MERGED+ 2 MORESESSION_SUMMARIZED

Shipped

8/27/2026, 3:07:30 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
stack72 assigned stack728/27/2026, 2:00:34 PM

Sign in to post a ripple.