API KEY AUTHENTICATION

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

Key formats

Type	Prefix	Example
Personal key	swamp_	swamp_a1b2c3d4e5f6... (32 hex)
Collective token	swamp_org_	swamp_org_a1b2c3d4e5... (32 hex)

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:

Field	Description
serverUrl	Server the key authenticates against
apiKey	The raw API key (swamp_ prefix)
apiKeyId	Key ID for revocation tracking
username	Authenticated username
collectives	Cached collective membership slugs

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

Variable	Purpose
SWAMP_API_KEY	API key for authentication (overrides auth.json)
SWAMP_CLUB_URL	Server URL override

Scope

Personal keys create a full user session. The authenticated user's identity, roles, and collective memberships are all available. Commands that require a user context (extension push, issue submit) 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.

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

Role requirements

Operation	Required role
Create personal key	Any authenticated user
Create collective token	Owner or admin
Revoke collective token	Owner or admin
Delete collective token	Owner or admin

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)

Method	Endpoint	Description
POST	/api/auth/api-key/create	Create a key
GET	/api/auth/api-key/list	List keys
POST	/api/auth/api-key/update	Update a key
POST	/api/auth/api-key/delete	Delete a key

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

Collective tokens

Method	Endpoint	Description
GET	/api/v1/collectives/{slug}/api-tokens	List tokens
POST	/api/v1/collectives/{slug}/api-tokens	Create a token
PATCH	/api/v1/collectives/{slug}/api-tokens/{tokenId}	Revoke a token
DELETE	/api/v1/collectives/{slug}/api-tokens/{tokenId}	Delete a token

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

CLI commands that require authentication

Command	Key type
swamp auth whoami	Personal
swamp extension push	Personal
swamp extension yank	Personal
swamp extension unyank	Personal
swamp extension deprecate	Personal
swamp extension undeprecate	Personal
swamp issue submit	Personal
swamp issue ripple	Personal
swamp issue get	Personal