API KEY AUTHENTICATION

API keys authenticate CLI commands and programmatic API requests. There are two types: personal keys and collective tokens.

Key formats

Authentication headers

API requests accept either header:

x-api-key: swamp_a1b2c3...

Authorization: Bearer swamp_a1b2c3...

The CLI sends Authorization: Bearer when the user is logged in. The x-api-key header remains accepted for backwards compatibility and is still used internally on specific per-call paths (e.g. extension push, yank). When both are present, Authorization takes precedence.

Device identity

In addition to the auth header, the CLI sends Swamp-Distinct-Id on every request to /api/*:

Swamp-Distinct-Id: c2f3eae0-d758-4174-9e8d-7b3f9a000001

The value is a per-device UUID lazy-created and stored by the CLI at ~/.config/swamp/identity.json. It enables stable per-device attribution for telemetry on requests that carry no API key — without it the server falls back to a per-request anon_* hash that changes on every call from the same machine.

The header is untrusted:

• It never authenticates or authorizes a request.
• It never resolves to a user record server-side.
• A session or API key always wins over the header when computing the distinct_id for an event.
• The server validates the value as a canonical UUID and falls back to the anon_* IP+UA hash on any other input.

Credential storage

The CLI stores credentials in auth.json in the Swamp config directory: $SWAMP_CONFIG_DIR, $SWAMP_HOME/config, $XDG_CONFIG_HOME/swamp, or ~/.config/swamp, the first that applies. File permissions are set to 0o600. Writes are atomic (temporary file, then rename) to prevent corruption.

The stored structure contains:

When SWAMP_API_KEY is set, the CLI caches the identity it resolved in auth.json and keys the cache on apiKeyFingerprint. A different key, or a file written by an older CLI that stored the key's first 12 characters instead, reads as stale and the identity is fetched again.

Verification state

The CLI also keeps the state of its account check in the config directory. Each file has permissions 0o600. swamp auth logout deletes all of them.

Credential precedence

1. --club-api-key-file (swamp serve, swamp serve check-config and swamp serve daemon enable only)
2. SWAMP_API_KEY_FILE environment variable
3. SWAMP_API_KEY environment variable
4. auth.json in the Swamp config directory

SWAMP_API_KEY_FILE and SWAMP_API_KEY are mutually exclusive: with both set and no --club-api-key-file, every command fails with SWAMP_API_KEY and SWAMP_API_KEY_FILE are mutually exclusive — unset one of them. A key file is read on every command and trimmed of whitespace; a missing, unreadable or empty file is an error.

The server is SWAMP_CLUB_URL if set, otherwise the serverUrl in auth.json, otherwise https://swamp-club.com.

When a collective key is set from any of the first three sources, swamp auth login and swamp auth logout are disabled.

Environment variables

SWAMP_SIGNIN_TOKEN is used only when it was issued for the active API key; a signin token for any other key is ignored. It has no file variant.

Scope

Personal keys create a full user session. The authenticated user's identity, roles, and collective memberships are all available. Most CLI commands that require authentication work with personal keys.

Collective tokens create a collective context only. They do not create a user session. The middleware sets collectiveTokenContext with the collective ID, slug, and token ID. Actions performed with a collective token are attributed to the collective, not to any individual user. Some commands — such as swamp extension push — accept collective tokens for CI/CD use cases where no individual operative is involved.

Personal keys grant access to all collectives the user belongs to. Collective tokens are scoped to a single collective.

Collective token scopes

A personal key carries all scopes implicitly. A collective token must include the required scope explicitly; without it the server returns HTTP 403.

Role requirements

Limits

Each collective can have a maximum of 25 API tokens.

Expiration

Collective tokens support an optional expiration date set at creation time. Expiration is enforced at verification — an expired token is rejected even if it is still enabled.

A personal key minted by swamp auth login expires 90 days after creation; logging in again mints a fresh one. Keys minted before this limit keep no expiry. Personal keys created from the web UI do not expire.

Key lifecycle

1. Created — key is generated, raw value shown once, hash stored
2. Enabled — key authenticates requests normally
3. Revoked — key is disabled and can no longer authenticate; remains visible in the UI
4. Deleted — key is permanently removed

Revoked keys cannot be re-enabled.

Security

Keys are hashed with SHA-256 (base64url encoding) before storage. The raw key is returned only at creation time. The full hash is never exposed in API responses or the web UI.

Fingerprints

A key's fingerprint is the first 16 characters of the lowercase hex SHA-256 of the full key. It names a key without revealing it and cannot be used to authenticate. The same value appears in:

• the Fingerprint column of the Access Tokens panel on /u/<username>
• the Fingerprint column of a collective's token list in its settings
• swamp auth whoami, swamp auth token create and swamp auth token list
• the fingerprint field of the collective token API responses

To match a key you hold to its row, see Identify a key.

API endpoints

Personal keys (BetterAuth)

These endpoints require an active session (cookie or session token).

A personal key can also revoke itself, which is how a CLI discards its own credential:

It authenticates with the key being deleted (x-api-key or Authorization: Bearer) and takes no body — the key id comes from the credential, so a key can only delete itself. It answers 200 {"revoked": true, "id": "<keyId>"}, 403 for a collective token or a browser session, and 401 for a key that no longer exists. Another replica may keep accepting a revoked key for up to 60 seconds.

Collective tokens

These endpoints require an active session with owner or admin role on the collective. List and create responses carry each token's keyPrefix and its fingerprint as fingerprint. The create response also carries signinToken unless the server could not sign one; it is never returned again.

Collective management

The collective:read and collective:write scopes are honoured by the collective REST API — reading a collective, its members, its pending invitations, and its published extensions, plus updating its settings. See Collective API for the endpoint table, and /api/v1/openapi.json for the machine-readable description.

Membership writes (invite, remove, change role) accept a session only and cannot be driven by any bearer credential; the reason is on that page.

CLI Commands

swamp auth login

Authenticate with a Swamp server.

Default behavior opens a browser for device-flow authentication.

swamp auth logout

Remove stored authentication credentials. No flags.

swamp auth whoami

Show current authenticated identity. Aliased as swamp auth status. No flags. Use --json for structured output.

Personal key output:

stack72 (paul@swamp-club.com) on https://swamp-club.com
Fingerprint: 3afc78556734e019
Plan: Team
Collectives:
  swamp              Team  active
  system-initiative  Free
  stack72            Free  trial: 13 days left (ends 2026-08-19)

Plan is a roll-up: the strongest plan across every collective you belong to. It answers "am I paying for anything?" but not "which collective needs upgrading?" — that is what the per-collective list is for. Billing attaches to a collective, never to a user, so a private extension push is refused on the namespace's plan, not on yours.

The third column shows the collective's billing status when it is paying, and its trial when it is not. Three details worth knowing:

• Billing status is shown to owners and admins only. Plain members see the plan and its name but not the raw status, matching the access rules on the collective's billing page. When triaging a report from a member, expect the field to be missing rather than null.
• A paying collective never shows a trial, even if its 30-day clock is still running. In --json its trial is null.
• The trial grants no entitlement. Reaching day 31 changes what you are told, not what you can do.

Fingerprint is the fingerprint of the key in use, whether it comes from auth.json or SWAMP_API_KEY. --json carries it as fingerprint. The key id is not shown.

If the server sends no entitlement — a self-hosted or older swamp-club — whoami falls back to the single Collectives: a, b, c line.

Collective token output:

Collective token: myorg on https://swamp-club.com
Scopes: extensions:push, extensions:read
Fingerprint: a40f6d9d7459f9aa
Collectives: myorg

Collective token JSON output (--json):

{
  "authenticated": true,
  "serverUrl": "https://swamp-club.com",
  "collectiveToken": true,
  "collectiveSlug": "myorg",
  "scopes": ["extensions:push", "extensions:read"],
  "fingerprint": "a40f6d9d7459f9aa",
  "collectives": ["myorg"]
}

The collective token response omits the id, username, email, and name fields that appear in the personal key response.

swamp auth token create

Create a scoped API token for a collective from the CLI.

Requires personal authentication (swamp auth login) — collective tokens cannot create other tokens. Only collective owners and admins can create tokens.

The token key is shown once at creation time and cannot be retrieved later. A Fingerprint: line above it gives the token's fingerprint, computed locally from the new key; --json carries it as fingerprint. Maximum 25 tokens per collective.

When swamp-club issues a signin token with the new key, it is printed below the key under Signin token:, and --json carries it as signinToken. It is shown once and cannot be retrieved later. Set it as SWAMP_SIGNIN_TOKEN beside SWAMP_API_KEY.

swamp auth token list

List all API tokens for a collective.

Requires personal authentication (swamp auth login). Only collective owners and admins can list tokens.

The table output shows each token's name, id, fingerprint, scopes, creation date, and last-used date. Against a server that does not report fingerprints, the key prefix appears in the fingerprint's place. JSON output includes id, keyPrefix and fingerprint for each token. A token disabled with Revoke in the web UI appears with enabled: false in JSON output.

swamp auth token revoke

Permanently remove an API token from a collective. The token disappears from swamp auth token list and its key stops working. To disable a token and keep it listed, use Revoke in the collective's settings in the web UI.

Requires personal authentication (swamp auth login). Only collective owners and admins can revoke tokens. A removed token cannot be restored.

Use swamp auth token list --collective <slug> to find the token id.

swamp auth server-login

Store a server token for a swamp serve instance — subsequent --server commands use it automatically.

CLI commands with key-type requirements

Every CLI command needs a credential except those listed in Swamp Account Requirement. The commands below additionally require a particular key type, or a scope when run with a collective token.

When a collective token is used with a command that requires a specific scope, the server returns HTTP 403 with:

{ "error": "This token requires the <scope> scope" }