Relationships
#4626 A serve set up through the normal OAuth path can't link people: its client isn't a collective's, and the app only sees club_unavailable
Opened by skunk-ape · 11/10/2026· Shipped 11/11/2026
Shipped, narrowed by Seth (swamp e1b652ac6, 2026-11-11). A serve whose swamp-club client isn't a collective's now refuses a link start with its own code and logs it. There's no collective registration at first start and no migration for existing serves. Serves that link people are set up with a collective API key, as in "Deploy with Headless OAuth". "Expected" below describes what shipped.
A swamp serve set up the standard way can't link anyone to an integration, and nothing says why.
What happens
Following "Set Up OAuth Authentication", serve's first start registers its swamp-club OAuth client through the browser approval (swamp serve --auth-mode oauth --allowed-collectives <collective> --admins <you>, then approve the device code). That client is owned by the person who approved it, with no collective.
Everything else works: people sign in, grants apply, and swamp access integration register succeeds. But every link start fails:
- serve asks swamp-club's link capabilities route, and swamp-club answers
403 client_not_collective, because links need a client owned by a collective; - serve tells the app
502 club_unavailable, "swamp-club could not be reached or refused this serve"; - serve logs nothing about it.
It reads as an outage. The only fix today is to throw away the stored client and start serve again with a collective API token (swamp auth token create --collective <slug> --scopes oauth:manage,serve:*, as in "Deploy with Headless OAuth"), which registers a collective-owned client.
To reproduce
- Use a collective with serve links available to it.
- Start serve with
--auth-mode oauth --allowed-collectives <that collective> --admins <an owner>, and approve the first-start device code in the browser as that owner. swamp access integration register demo --name Demo --ceiling 'run,read=workflow:<a workflow>'.POST /api/v1/delegations/linkswith the printed credential as a bearer token and a validexternalandceilingbody.- The answer is
502 {"code":"club_unavailable"}. swamp-club's log showsGET /api/v1/serve/links/capabilitiesanswered 403.
Seen on swamp origin/main and swamp-club main, 2026-11-10, against a local swamp-club.
Expected
A link start on a serve whose swamp-club client isn't owned by a collective (for example one set up through the browser device approval) is refused with 409 links_require_collective_client and a message saying the client isn't a collective's, instead of 502 club_unavailable. Serve logs a warning. A serve set up with a collective API key links as before.
Not done, by decision: registering the first-start client under the --allowed-collectives collective, and moving an existing serve from a person-owned client to a collective one. "Set Up OAuth Authentication" says a serve set up through the device approval can't link people, and points to "Deploy with Headless OAuth" (in #4619).
Notes
- The shipped change is swamp only. No swamp-club change was needed.
- Check against swamp-club#4585 (collective clients can't complete
authorization_code) and #4498's client ownership and rotation. - Found while writing the customer integration guide (swamp-club#4619), which documents the headless path.
- #4585 looks like a storage bug: collective clients store redirect URIs as JSON, which better-auth splits on commas. Serve isn't affected, since it signs people in through the device grant.
invalid_clientat link start still answersclub_unavailable.
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.