Skip to main content

MANAGE ACCESS GRANTS

This guide shows you how to control what authenticated users can do on a swamp serve instance using authorization grants.

Create an allow grant

Grant a user permission to run all behaviors:

swamp access grant create --subject user:sarah --allow run --on 'behavior:*' \
  --server wss://swamp.example.com

The server stores a behavior: selector as model:, so listings show model:*.

swamp access policy create is an alias for swamp access grant create — they do the same thing.

Create a deny grant

Deny grants override allow grants. To block a user from reading specific data:

swamp access grant create --subject user:adam --deny read \
  --on 'data:@acme/secrets-*' --server wss://swamp.example.com

Add a CEL condition

Restrict a grant to specific contexts using --when:

swamp access grant create --subject user:sarah --allow run \
  --on 'workflow:@acme/*' --when 'tags.env == "staging"' \
  --server wss://swamp.example.com

The condition is evaluated against resource fields at access-check time. See the CEL Expressions reference for the full syntax.

Reload the policy snapshot

Grants are staged until you reload. This is the safety mechanism — a bad policy does not take effect until deliberately applied:

swamp access reload --server wss://swamp.example.com

If you want grants to take effect immediately without a manual reload, start the server with --grant-reload auto:

swamp serve --auth-mode token --admins 'user:paul' --grant-reload auto

swamp access reload applies the staged changes on the instance it reaches. You do not need to reload every peer: other serve instances on the same S3, GCS or v2 filesystem datastore pick up a grant, revoke or group change within one --datastore-poll-interval (default 30s), in either reload mode. See Multiple instances.

List grants

swamp access grant list --server wss://swamp.example.com

Revoke a grant

swamp access grant revoke <grant-id> --server wss://swamp.example.com

After revoking, reload the policy snapshot for the change to take effect (unless using --grant-reload auto).

Check access for a specific user

Admins can check whether a subject is allowed to perform an action:

swamp access check --subject user:sarah --action run \
  --on 'behavior:hello' --server wss://swamp.example.com

To simulate IdP group memberships for idp-group: grants, run the check locally against the repository's grants with --groups:

swamp access check --subject user:adam --action run \
  --on 'workflow:@acme/deploy' --groups platform-eng,ops

To test condition evaluation against resource fields, also run the check locally:

swamp access check --subject user:adam --action run \
  --on 'workflow:@acme/deploy' --field tags.env=staging

A check against a server refuses --groups, --collectives and --field: the server evaluates conditions against its own resource context, and knows IdP groups and collectives only for your own session, so checking another subject there does not reflect its idp-group: grants.

Admin grants from config

The --admins flag materializes admin grants at startup. Admins receive admin on access:*, which implies all actions on all resources.

To add an admin: add the principal to --admins and restart the server. To remove an admin: remove the principal from --admins and restart. The config is reconciled on every boot — config is the source of truth.

← PreviousDeploy with Headless OAuthNext →Manage Groups