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.

Unauthenticated connections

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

Set Up TLS for swamp serve — required for off-loopback deployments
Manage Access Grants — control what authenticated users can do
Serve Flags — full flag and environment variable reference