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.

Every Swamp command except a few exempt ones needs one of these credentials. See Swamp Account Requirement for what is enforced and which commands are exempt.

Prerequisites

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...

To keep the key out of the environment, write it to a file and set SWAMP_API_KEY_FILE to the file's path instead:

export SWAMP_API_KEY_FILE=/run/secrets/swamp_api_key

Set one or the other. With both set, every command fails with SWAMP_API_KEY and SWAMP_API_KEY_FILE are mutually exclusive — unset one of them.

Every CLI command uses this key in place of a stored login. 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 your profile at https://swamp-club.com/u/<username>
  3. Expand the Access Tokens panel
  4. Enter a label and click Generate
  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. Open swamp-club.com/orgs and select the collective
  2. Open the Settings tab
  3. Under Collective Tokens, enter a label and select the scopes
  4. Click Generate
  5. Copy both values immediately — the SWAMP_API_KEY and the SWAMP_SIGNIN_TOKEN are shown only once. CI needs both; see Run Swamp in CI

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:*

You will see output like:

Token: cli-myhost-1790850000000
Collective: myorg
Scopes: extensions:push, serve:*
Fingerprint: 3f9a1c0e7b2d4a61

  swamp_org_abc123...

Signin token: (set as SWAMP_SIGNIN_TOKEN beside SWAMP_API_KEY in CI)

  eyJmcHIiOi...

These are shown once and will not be displayed again — store them now.

The first value is the API key; the second is the signin token. Neither can be retrieved later. Copy both 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

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

Run Swamp in CI

CI authenticates with a collective token and its signin token, set as two secrets: SWAMP_API_KEY and SWAMP_SIGNIN_TOKEN.

Store the signin token as soon as it is shown. It is displayed once, when the collective token is created, and cannot be retrieved later. It is what lets CI keep running when swamp-club.com is unreachable or rate-limiting. Without it, every CI job must reach swamp-club.com before Swamp will run, so an outage blocks your pipelines. Keep it beside SWAMP_API_KEY in your secret manager, with the same care.

Get the API key and signin token

Create a collective token by either route; both show the two values together:

If no signin token is shown, the API key still works, but CI depends on reaching swamp-club.com for every job.

Set the secrets

Add both values as secrets in your CI system, then expose them to Swamp as environment variables. In GitHub Actions:

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      SWAMP_API_KEY: ${{ secrets.SWAMP_API_KEY }}
      SWAMP_SIGNIN_TOKEN: ${{ secrets.SWAMP_SIGNIN_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - run: curl -fsSL https://swamp-club.com/install.sh | sh
      - run: swamp workflow run deploy

The signin token is read only from SWAMP_SIGNIN_TOKEN; there is no file variant. The API key can come from SWAMP_API_KEY_FILE instead.

Share one token across a parallel matrix

Every job in a matrix can use the same collective token. swamp-club.com rate-limits a collective token per runner: each client IP address gets its own per-minute request budget, so jobs on separate runners do not draw on each other's. The token as a whole has a much higher shared ceiling across all its runners. If a matrix is wide enough to reach that ceiling, split its jobs across two or more collective tokens.

Replace a token without a signin token

A collective token created before signin tokens existed, or created on the web before the panel showed one, has none, and one cannot be issued for it later. To get one:

  1. Create a new collective token with the same scopes
  2. Store its API key and signin token as your CI secrets
  3. Revoke the old token (see Revoke a collective token from the CLI)

Do the same if the signin token is lost.

Rotate a CI token

A signin token only matches the API key it was issued with. To rotate, create a new collective token, replace both secrets, then revoke the old token. Replacing only SWAMP_API_KEY leaves CI with no signin token for the new key.

Use a personal key in CI

A personal API key in SWAMP_API_KEY also works, but no signin token is issued for it, so every job depends on reaching swamp-club.com. Use a collective token for CI.

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                                    STATUS   FINGERPRINT       SCOPES                    CREATED                   LAST USED
ci-deploy       3e6626ac-8921-48c1-bcdf-803e4b5f25da  active   9f2c41d07ab3e815  extensions:push, serve:*  2026-07-31T07:06:01.797Z  2026-08-15T04:40:53.297Z
staging-server  8d03ef2d-3f6d-4fb8-9a10-3c3880d6ebed  revoked  47e0b9c2d5a1f368  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:

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

The <token-id> is the UUID shown by swamp auth token list. The token's key stops working, and the token stays in the list as revoked. Requires Swamp v20261103.162057.0-sha.1ac19410 or later. Older versions delete the token on revoke.

You must be logged in with a personal account that has the owner or admin role on the collective, or use a collective token holding tokens:mint to revoke the tokens it minted.

Delete a collective token from the CLI

Use swamp auth token delete to permanently remove a token:

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

The command asks you to confirm; pass --yes to skip the prompt in a script. The token disappears from the list, its key stops working, and it cannot be restored. Requires Swamp v20261103.162057.0-sha.1ac19410 or later.

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, and its signin token as SWAMP_SIGNIN_TOKEN:

export SWAMP_API_KEY=swamp_org_abc123...
export SWAMP_SIGNIN_TOKEN=eyJmcHIiOi...

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.

Identify a key

Every key has a fingerprint that names it without revealing it. Match a key you hold to its row by fingerprint — for example, to revoke only the key that leaked. Rows on your profile's Access Tokens panel and in a collective's token list each show one.

To see the fingerprint of the key your CLI uses, run swamp auth whoami. You will see output like:

$ swamp auth whoami
<username> (<email>) on https://swamp-club.com
Fingerprint: 3afc78556734e019
...

For any other key, such as one found in a CI log or a commit, pass it in SWAMP_API_KEY:

$ SWAMP_API_KEY=<token> swamp auth whoami
Collective token: <collective> on https://swamp-club.com
Scopes: extensions:*
Fingerprint: a40f6d9d7459f9aa
...

This works while the key is still valid. swamp auth token create also prints a new token's Fingerprint: line, next to the one-time key.

Find the row with that fingerprint on your profile's Access Tokens panel. For a collective token, look in the collective's settings or run swamp auth token list --collective <slug>, which shows a FINGERPRINT column. Then revoke that key.

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 the Access Tokens panel on your profile (/u/<username>), 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, or swamp auth token delete <token-id> --collective <slug> to remove it permanently.

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