Skip to main content

ACCESS COMMANDS

swamp access

Manage authorization policies (grants), groups, and access checks.

Subcommands

Command Alias Description
token Manage server tokens for user authentication
grant policy Manage authorization grants
group Manage local and IdP groups
can-i Check your own permissions against the server's grants
check Explain whether a subject can perform an action
reload Rebuild the policy snapshot from current grants and groups

Token resolution

All --server subcommands resolve authentication credentials in this order:

  1. --token flag or SWAMP_SERVER_TOKEN environment variable — an inline <name>.<secret> credential.
  2. --token-file flag or SWAMP_SERVER_TOKEN_FILE environment variable — a path to a file containing the <name>.<secret> credential.
  3. Stored credential from a previous swamp auth server-login.

The first source that provides a value wins. When using --token-file, the file must contain the bare credential string with no surrounding whitespace or newlines.

swamp access token

swamp access token mint

Mint a server token for user authentication. When a datastore is configured, the token secret is stored in the control-plane vault and can be retrieved with swamp access token reveal. The --vault flag is rejected in this mode because storage is managed by the control plane. For local repos without a datastore, the plaintext is stored in the vault selected by --vault.

swamp access token mint <name> --principal <principal>
Flag Required Default Description
--principal Yes Principal identity (e.g., user:adam)
--email No Display email for the token holder
--duration No 30d Token lifetime (e.g., 30m, 1h, 24h, 7d)
--vault No Vault for the token plaintext (rejected when a datastore is configured — secrets use the control-plane vault)
--server No Target a remote server (env: SWAMP_SERVE_URL)
--token No Server token (falls back to stored credential)
--token-file No Token file path (env: SWAMP_SERVER_TOKEN_FILE)

swamp access token list

List server tokens: state, principal, expiry, and last use.

swamp access token list
Flag Required Default Description
--server No Target a remote server (env: SWAMP_SERVE_URL)
--token No Server token (falls back to stored credential)
--token-file No Token file path (env: SWAMP_SERVER_TOKEN_FILE)

swamp access token revoke

Invalidate a server token before it expires.

swamp access token revoke <name>
Flag Required Default Description
--server No Target a remote server (env: SWAMP_SERVE_URL)
--token No Server token (falls back to stored credential)
--token-file No Token file path (env: SWAMP_SERVER_TOKEN_FILE)

swamp access token rotate

Revoke an existing token and mint a replacement with the same name and principal. When a datastore is configured, the new token secret is stored in the control-plane vault. For local repos without a datastore, it is stored in the same vault as the original. The output includes a swamp access token reveal command to retrieve the new credential.

swamp access token rotate <name>
Flag Required Default Description
--server No Target a remote server (env: SWAMP_SERVE_URL)
--token No Server token (falls back to stored credential)
--token-file No Token file path (env: SWAMP_SERVER_TOKEN_FILE)

swamp access token reveal

Show the full authentication credential for a server token. The secret is written directly to stdout (not through the logger) so it can be piped or captured.

swamp access token reveal <name>

The command reads the token record, retrieves the plaintext secret from the datastore or the control-plane vault, and displays the full <name>.<secret> credential string.

Flag Required Default Description
-y, --yes No Skip confirmation prompt
-f, --force No Skip confirmation prompt (alias for --yes)
--repo-dir <dir> No Repository directory (env: SWAMP_REPO_DIR)

Error cases:

  • Token not found: Error: Server token '<name>' not found
  • Token revoked: Error: Server token '<name>' has been revoked
  • Expired tokens are revealed with a warning

JSON output (--json):

{
  "name": "my-token",
  "token": "my-token.<secret>",
  "expired": false
}

The expired field is true when the token has passed its expiry date. Storage details are excluded from JSON output.

Shared-vault handoff

When a datastore is configured, server-token secrets are stored in the control-plane vault. To copy a credential to a different vault without changing its control-plane storage, pipe reveal into vault put:

$ swamp access token reveal <name> --repo-dir <repo> --yes --json \
    | jq -re .token \
    | swamp vault put <vault> server-token-<name> --yes

This writes the full <name>.<secret> credential to the destination vault. The control-plane vault remains the authoritative store — the copy is a convenience for systems that read credentials from a specific vault.

swamp access grant

swamp access policy is an alias for swamp access grant.

swamp access grant create

Create a new authorization grant.

swamp access grant create --subject <subject> --on <resource>
Flag Required Description
--subject Yes Grant subject (e.g., user:adam, group:release-managers, idp-group:platform-eng)
--allow No Actions to allow (comma-separated: run, read, write, approve, admin)
--deny No Actions to deny (comma-separated)
--on Yes Resource selector (e.g., workflow:@acme/*, model:hello)
--methods No Restrict to specific model methods (comma-separated, e.g., read,list)
--when No CEL condition (e.g., tags.env == "staging")
--server No Target a remote server (env: SWAMP_SERVE_URL)
--token No Server token (falls back to stored credential)
--token-file No Token file path (env: SWAMP_SERVER_TOKEN_FILE)

Exactly one of --allow or --deny must be provided.

swamp access grant list

List authorization grants.

swamp access grant list
Flag Required Description
--server No Target a remote server (env: SWAMP_SERVE_URL)
--token No Server token (falls back to stored credential)
--token-file No Token file path (env: SWAMP_SERVER_TOKEN_FILE)

swamp access grant revoke

Revoke an authorization grant.

swamp access grant revoke <grant_id>
Flag Required Description
--server No Target a remote server (env: SWAMP_SERVE_URL)
--token No Server token (falls back to stored credential)
--token-file No Token file path (env: SWAMP_SERVER_TOKEN_FILE)

swamp access group

swamp access group create

Create a local group.

swamp access group create <name>

swamp access group add-member

Add a principal to a group.

swamp access group add-member <group> <principal>

swamp access group remove-member

Remove a principal from a group.

swamp access group remove-member <group> <principal>

swamp access group list

List all groups.

swamp access group list

swamp access group list-idp

List IdP groups observed from authenticated users on a server. Unlike the other group subcommands (which manage local groups), list-idp queries a running server to show groups aggregated from active server tokens' OAuth userinfo.

swamp access group list-idp --server <url>
Flag Required Default Description
--server Yes Server to query (env: SWAMP_SERVE_URL)
--token No Server token (falls back to stored credential or env)
--token-file No Token file path (env: SWAMP_SERVER_TOKEN_FILE)
--json No Output in JSON format

Required permission: read on access:group

Output columns:

Column Description
GROUP IdP group name (as received from the OAuth provider)
ACTIVE TOKENS Number of active server tokens carrying this group
LAST SEEN Timestamp of the most recent token carrying this group

swamp access group members

List members of a group.

swamp access group members <name>

swamp access can-i

Check your own permissions against the server's grants.

swamp access can-i
Flag Required Description
--action No Action to check (run, read, write, approve, admin)
--on No Resource to check (e.g., workflow:@acme/deploy)
--method No Model method name to check against method-scoped grants
--collectives No Comma-separated IdP group memberships to simulate
--server No Target a remote server (env: SWAMP_SERVE_URL)
--token No Server token (falls back to stored credential)
--token-file No Token file path (env: SWAMP_SERVER_TOKEN_FILE)

Without --action and --on, lists everything you can do. With both, checks a specific permission. Use --method to test whether a method-scoped grant permits a specific method.

swamp access check

Explain whether a subject can perform an action on a resource. Requires admin access.

swamp access check --subject <subject> --action <action> --on <resource>
Flag Required Description
--subject Yes Subject to check (e.g., user:adam)
--action Yes Action to check (run, read, write, approve, admin)
--on Yes Resource to check (e.g., workflow:@acme/deploy)
--method No Model method name to check against method-scoped grants
--collectives No Comma-separated IdP group memberships to simulate
--field No Resource field for condition evaluation (key=value, repeatable)
--server No Target a remote server (env: SWAMP_SERVE_URL)
--token No Server token (falls back to stored credential)
--token-file No Token file path (env: SWAMP_SERVER_TOKEN_FILE)

swamp access reload

Rebuild the policy snapshot from current grants and groups. Required after grant or group changes when using the default --grant-reload manual mode.

swamp access reload
Flag Required Description
--server No Target a remote server (env: SWAMP_SERVE_URL)
--token No Server token (falls back to stored credential)
--token-file No Token file path (env: SWAMP_SERVER_TOKEN_FILE)

When a grants/ directory exists, reload reads and validates all files in it before rebuilding the snapshot. Accepted file extensions are .yaml and .yml. Subdirectories are ignored — the directory is flat.

The reconciler compares file contents against existing file:* grants. New entries are created, removed entries are revoked, and unchanged entries are skipped. Grants with other sources (method, config, extension:*) are not affected.

If any file fails validation, the entire reload is rejected — the current policy snapshot remains unchanged and no grants are created or revoked.

The response includes a reconciliation summary (created, revoked, unchanged counts) and the full list of active grants.

← Previousswamp serveNext →Authorization