Skip to main content

SET UP TOKEN AUTHENTICATION

This guide shows you how to enable token-based authentication on swamp serve so that only authorized users can connect.

Start the server with token auth

Pass --auth-mode token and --admins with at least one admin principal:

swamp serve --auth-mode token --admins 'user:paul'

The --admins flag accepts a comma-separated list of principal IDs. These principals receive full admin access on every server start — see admin materialization for how this works.

Important

Off-loopback binding (e.g., --host 0.0.0.0) requires both TLS and authentication. The server refuses to start without them. See Set Up TLS for certificate setup.

Mint tokens

An admin mints tokens for each user. The token plaintext is shown once — copy it and distribute it securely:

swamp access token mint paul-token --principal user:paul
swamp access token mint sarah-token --principal user:sarah

Tokens expire after 30 days by default. To set a custom duration:

swamp access token mint ci-token --principal user:ci --duration 7d

Store a token for automatic use

Users store their token locally so that subsequent --server commands authenticate automatically:

swamp auth server-login --server wss://swamp.example.com --token 'paul-token.<secret>'

The credential is saved to ~/.config/swamp/servers.json. Any command that uses --server wss://swamp.example.com will use the stored token automatically.

Set SWAMP_SERVE_URL for convenience

To avoid typing --server on every command:

export SWAMP_SERVE_URL=wss://swamp.example.com
swamp access can-i    # no --server needed

List tokens

swamp access token list

Shows each token's name, state, principal, expiry, and last use.

Revoke a token

swamp access token revoke sarah-token

The token is immediately invalidated. Connections using the revoked token receive HTTP 401.

Rotate a token

swamp access token rotate paul-token

This revokes the existing token and mints a replacement with the same name and principal. The new plaintext is shown once.

Connect with a token

To connect from a CLI client or any environment that supports custom headers, pass the token as a Bearer header on the WebSocket upgrade request:

curl --include --no-buffer \
  -H 'Connection: Upgrade' \
  -H 'Upgrade: websocket' \
  -H 'Authorization: Bearer paul-token.<secret>' \
  wss://swamp.example.com

To connect from a browser, pass the token via the Sec-WebSocket-Protocol header:

const ws = new WebSocket(
  "wss://swamp.example.com",
  "bearer.paul-token.<secret>",
);

To connect via query parameter:

wss://swamp.example.com?token=paul-token.<secret>

If multiple transports are present, the server uses the first match: Authorization header, then Sec-WebSocket-Protocol, then query parameter.

See Serve Flags — WebSocket token transports for the full transport reference, and Token transports on WebSocket for why multiple transports exist.

Unauthenticated connections

Any connection without a valid token receives HTTP 401. There is no anonymous fallback when --auth-mode token is active.

← Previousswamp serveNext →Set Up OAuth Authentication