AUTHENTICATE WITH API KEYS

This guide shows you how to authenticate with Swamp using API keys — through the CLI, the web UI, or environment variables.

Prerequisites

• The Swamp CLI installed (curl -fsSL https://swamp-club.com/install.sh | sh)
• A Swamp account (swamp-club.com)

Log in with the CLI

Run swamp auth login to authenticate via your browser:

$ swamp auth login

Your browser opens to the Swamp login page. After you sign in, the CLI confirms authentication and stores your credentials locally.

Verify your identity:

$ swamp auth whoami

You will see output like:

stack72 (paul@systeminit.com) on https://swamp-club.com
Collectives: swamp, system-initiative, stack72

Log in without a browser

Pass credentials directly to skip the browser flow. The --username flag accepts either a username or an email address:

$ swamp auth login --username alice --password secret --no-browser

$ swamp auth login --username alice@example.com --password secret --no-browser

Omit --password to be prompted for it interactively — the username is already provided via the flag, so only the password is prompted.

Pipe a password from stdin

You can pipe a password to avoid interactive prompts entirely. This is useful in scripts and CI environments where no TTY is available:

$ printf 'mypassword\n' | swamp auth login --username alice --no-browser

The --username flag is required when piping — without it the CLI prompts for both username and password, which conflicts with the pipe.

Use an environment variable

Set SWAMP_API_KEY to authenticate without storing credentials to disk:

export SWAMP_API_KEY=swamp_abc123...

All CLI commands that require authentication will use this key. See the API Key Authentication reference for precedence rules.

Create a personal API key in the web UI

If you need a key for custom integrations outside the CLI:

1. Sign in to swamp-club.com
2. Open Settings
3. Expand the Access Tokens panel
4. Enter a name and click Create
5. Copy the key immediately — it is shown only once

Create a collective API token

To create a token scoped to a collective, you need the owner or admin role on that collective.

1. Navigate to the collective's settings page
2. Expand the API Tokens panel
3. Enter a name and optionally set an expiration date
4. Click Create
5. Copy the token immediately — it is shown only once

Create a collective token from the CLI

Use swamp auth token create to provision a collective token without the web UI. This is useful in CI/CD pipelines or automation scripts where you want to create tokens programmatically.

You must be logged in with a personal account that has the owner or admin role on the collective.

Log in first

$ swamp auth login

Create the token

Specify the collective and the scopes to grant:

$ swamp auth token create --collective myorg --scopes extensions:push,serve:*

The token key is displayed once and cannot be retrieved later. Copy it immediately.

Add --name to set a custom label (defaults to cli-<hostname>-<timestamp>):

$ swamp auth token create --collective myorg --scopes extensions:push --name ci-deploy

Use --json for structured output suitable for scripting:

$ swamp auth token create --collective myorg --scopes extensions:push --json

Export the token for CI

Store the token as a CI secret (e.g. SWAMP_API_KEY) and export it in your pipeline:

export SWAMP_API_KEY=swamp_org_abc123...

Verify the token works:

$ swamp auth whoami

Refer to the API Key Authentication reference for the full flag list and behavior details.

Use a collective token with the CLI

Collective tokens let you authenticate as a collective rather than an individual operative. This is useful in CI/CD pipelines where no personal login is available.

Set the token

Export a collective token (prefixed swamp_org_) as SWAMP_API_KEY:

export SWAMP_API_KEY=swamp_org_abc123...

Verify the token

Run swamp auth whoami to confirm the token is valid:

$ swamp auth whoami

You will see output like:

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

Use --json for structured output:

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

Use a collective token for team features

If you need to run external datastores, non-local vaults, or authenticated swamp serve with a collective token, include the appropriate scope when creating the token:

• datastore:* — for swamp datastore setup extension
• vault:* — for swamp vault create with non-local vault types
• serve:* — for swamp serve --auth-mode token or --auth-mode oauth

Refer to the API Key Authentication reference for the full scope table.

Push an extension with a collective token

If the token has the extensions:push scope, you can push extensions to the collective's namespace:

$ swamp extension push

The CLI verifies that the token's collective owns the extension namespace before uploading.

Scope errors

If the token lacks a required scope, the server returns a 403 error:

Error: This token requires the extensions:push scope

Check the token's scopes with swamp auth whoami and create a new token with the required scopes in the collective's settings page if needed.

Revoke or delete a key

CLI-created keys: Run swamp auth logout to remove stored credentials and revoke the key.

$ swamp auth logout

Web UI keys: Open Settings > Access Tokens, click Revoke to disable the key (it can no longer authenticate but remains visible), or Delete to remove it permanently.

Collective tokens: Open the collective's settings, find the token, and click Revoke or Delete.

Connect to a different server

Pass --server to authenticate against a server other than the default:

$ swamp auth login --server https://registry.example.com

You can also set the SWAMP_CLUB_URL environment variable.

Refer to the API Key Authentication reference for the full details on key formats, scoping, and credential precedence.