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 anonymous CLI traffic (extension search, info, pulls without login) — 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 ~/.config/swamp/auth.json (or $XDG_CONFIG_HOME/swamp/auth.json). File permissions are set to 0o600. Writes are atomic (temporary file, then rename) to prevent corruption.

The stored structure contains:

Credential precedence

1. SWAMP_API_KEY environment variable (highest priority)
2. ~/.config/swamp/auth.json file
3. Default server: https://swamp-club.com

When SWAMP_API_KEY is set, swamp auth login and swamp auth logout are disabled.

Environment variables

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. Personal keys created by the CLI 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 key hash is never exposed in API responses or the web UI.

API endpoints

Personal keys (BetterAuth)

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

Collective tokens

These endpoints require an active session with owner or admin role on the collective.

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
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. The trial is still present in --json.
• The trial grants no entitlement. Reaching day 31 changes what you are told, not what you can do.

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
Collectives: myorg

Collective token JSON output (--json):

{
  "authenticated": true,
  "serverUrl": "https://swamp-club.com",
  "collectiveToken": true,
  "collectiveSlug": "myorg",
  "scopes": ["extensions:push", "extensions:read"],
  "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. Maximum 25 tokens per collective.

swamp auth server-login

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

CLI commands that require authentication

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" }