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

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

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

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 'model:hello' --server wss://swamp.example.com

To simulate IdP group memberships in the check:

swamp access check --subject user:adam --action run \
  --on 'workflow:@acme/deploy' --collectives platform-eng,ops \
  --server wss://swamp.example.com

To test condition evaluation against resource fields:

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

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.

Related

• Authorization — full reference for subjects, effects, actions, resource selectors, and deny-wins semantics
• Check Your Permissions — how users check their own access
• Real-World Scenarios — team isolation, deny overrides, and more