Skip to main content
← Back to list
01Issue
BugOpenSwamp ClubPublic
AssigneesNone

Relationships

#3446 Docs: serve-flags.md admin/allowed-user resolution is stale (pinned names, oauth:manage for lookups, plain usernames only)

Opened by stack72 · 10/14/2026

Summary

content/manual/reference/swamp-serve/serve-flags.md (the OAuth admin and allowed-user resolution notes, around lines 408-411) no longer matches how swamp serve resolves --admins and --allowed-users, after the fix for swamp-club#3435.

What to change

  • Remove the sentence saying a skipped name is checked again on each start when the API key is set, or whenever the lists change. A name recorded as not found stays skipped until it is removed from the list. This was already out of date before #3435.
  • Say that a resolved name is pinned: startup never looks it up again, including when the list is edited. To point a name at a different account, remove it, restart, then add it back.
  • Say that startup looks up only names it has no record of, so it needs a credential that can look users up only when a name is added: a login token, or a collective API token with the oauth:manage scope. A refused lookup (401 or 403) now names that scope in the error.
  • Say that each entry must be a plain username. In OAuth mode an entry containing a colon after the optional user: prefix (for example allowed:bob, group:eng, idp-group:eng) is skipped with an ERROR and is never looked up; groups are not supported in these lists with --auth-mode oauth.
  • swamp-club#3435 (the fix)
  • content/manual/how-to/swamp-serve/deploy-headless-oauth.md already says the API key needs oauth:manage; a cross-link from serve-flags.md would help operators who registered with the device grant and added an API key later.
02Bog Flow
◉OPEN○TRIAGED○IN PROGRESS○SHIPPED

Open

10/14/2026, 3:00:02 PM

No activity in this phase yet.

03Sludge Pulse
Editable. Press Enter to edit.

system commented 10/14/2026, 3:00:02 PM

Classified automatically when this issue was filed.

  • Type: Bug

If you feel this classification is incorrect, add a ripple to tell us so.

Sign in to post a ripple.