Skip to main content
← Back to list
01Issue
FeatureOpenSwamp CLIPublic
AssigneesNone

Relationships

#3843 auth token create --json fields key and signinToken are undocumented; no token-mode service setup page

Opened by reset · 10/23/2026

On 20261020.024627.0-sha.26dc044f (macOS 27), running swamp serve --auth-mode token as a system service on a host where nobody runs swamp auth login needs a collective token with serve:*, its signin token, and the environment names that carry them. Assembling that takes three pages and one undocumented field:

  • swamp auth token create --help documents --json only as Output in JSON format (non-interactive). The JSON object printed by src/presentation/output/auth_token_output.ts:33 is AuthTokenCreateData (src/libswamp/auth/token_create.ts:40): key, fingerprint, id, name, collective, scopes and, when issued, signinToken. The manual's auth token create section names fingerprint and signinToken but not key, the field that holds the token itself, and both values are shown once.
  • The serve guide's Token Management section says CI deployments set SWAMP_API_KEY and SWAMP_SIGNIN_TOKEN; the API key reference says serve needs serve:*; the service-unit paragraph in swamp serve --help covers SWAMP_HOME and SWAMP_CONFIG_DIR but not the credential.

Expected: one section under serve that says: create a collective token with serve:*, capture key and signinToken from --json, set SWAMP_API_KEY_FILE (or SWAMP_API_KEY) and SWAMP_SIGNIN_TOKEN in the unit, with the JSON field names so the capture can be piped into a secret store. Actual: the key field is learned by running the command once, and the sequence is reconstructed from the account requirement page, the API key reference and the serve guide.

Steps to reproduce:

  1. swamp auth token create --help: no field list for --json.
  2. Search the manual for signinToken: the field is named, key is not.

Prior: #1373 (shipped) documented auth token create; #2866 (closed) documented SWAMP_API_KEY_FILE and --club-api-key-file and added a Kubernetes example to the headless OAuth how-to (how-to/swamp-serve/deploy-headless-oauth.md). That page covers --auth-mode oauth; there is no equivalent for token mode as a service.

Suggestion: document every field of auth token create --json in the reference, and add a "run serve as a system service" how-to for token mode with the credential steps and a unit example beside the OAuth one.

02Bog Flow
◉OPEN○TRIAGED○IN PROGRESS○SHIPPED

Open

10/23/2026, 5:22:53 PM

No activity in this phase yet.

03Sludge Pulse

Sign in to post a ripple.