Skip to main content

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.

List collective tokens from the CLI

Use swamp auth token list to see all tokens for a collective:

$ swamp auth token list --collective myorg

You will see output like:

NAME              ID                                    PREFIX        SCOPES                    CREATED                   LAST USED
ci-deploy         3e6626ac-8921-48c1-bcdf-803e4b5f25da  swamp_org_ab  extensions:push, serve:*  2026-07-31T07:06:01.797Z  2026-08-15T04:40:53.297Z
staging-server    8d03ef2d-3f6d-4fb8-9a10-3c3880d6ebed  swamp_org_ff  serve:*                   2026-07-30T15:52:15.196Z  -

Use --json for structured output suitable for scripting:

$ swamp auth token list --collective myorg --json

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

Revoke a collective token from the CLI

Use swamp auth token revoke to disable a token so it can no longer authenticate:

$ swamp auth token revoke <token-id> --collective myorg

The <token-id> is the UUID shown by swamp auth token list. A revoked token remains visible in the token list but can no longer authenticate requests.

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

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 (CLI): Run swamp auth token list --collective <slug> to find the token id, then swamp auth token revoke <token-id> --collective <slug> to disable it.

Collective tokens (web UI): 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.

← PreviousSet Up Background AutoupdatingNext →Troubleshoot Your Swamp Repo