Authorization

Authorization in swamp serve is grant-based. Each grant binds a subject to an effect (allow or deny) on a set of actions against a resource selector. The server evaluates all matching grants at access-check time.

Default deny

If no grant matches a request, the request is denied. There is no implicit allow.

Subjects

A grant's --subject identifies who the grant applies to.

Format	Description
`user:<id>`	A specific authenticated user
`group:<name>`	Members of a local group managed via `swamp access group`
`idp-group:<collective-slug>`	Users whose IdP token includes the group

Local groups are resolved at policy reload time. IdP groups come from the OAuth provider's userinfo response, using the field specified by --groups-field (default: collectives).

Effects

Each grant has exactly one effect:

Effect	Meaning
`allow`	Permits the specified actions
`deny`	Blocks the specified actions

Deny wins

When both allow and deny grants match a request, deny wins. A deny grant always overrides an allow grant, regardless of specificity.

Actions

Action	Description
`run`	Execute a model method or workflow
`read`	Read data outputs, model definitions, vaults
`write`	Write data, create models
`admin`	Manage access: grants, tokens, groups

Actions are specified as comma-separated values in --allow or --deny.

Admin superuser

A grant of admin on access:* implies all actions on all resources. This is the superuser grant — the holder can perform any operation. The --admins flag materializes this grant for the listed principals on every server start.

Resource selectors

The --on flag specifies which resources the grant applies to.

Selector	Matches
`workflow:@acme/*`	All workflows in the `@acme` namespace
`workflow:@acme/deploy`	A specific workflow
`model:hello`	A specific model
`model:*`	All models
`data:*`	All data outputs
`data:@acme/secrets-*`	Data outputs matching the prefix
`access:*`	The access control system itself

The * wildcard matches any suffix.

CEL conditions

The --when flag adds a CEL expression that must evaluate to true for the grant to apply. Conditions are evaluated against resource fields at access-check time.

--when 'tags.env == "staging"'

See the CEL Expressions reference for the full syntax, operators, and available functions.

Resource fields can be passed to swamp access check using the --field flag for testing condition evaluation.

Grant source types

Grants can originate from different sources:

Source	Description
`method`	Created via `swamp access grant create`
`config`	Materialized from `--admins` at startup
`file`	Loaded from a declarative grants file
`extension:*`	Contributed by an extension

Policy snapshot

Grants and group memberships are compiled into a policy snapshot. The snapshot is rebuilt:

On swamp access reload
On every grant or group change when --grant-reload auto is active
On server start (including admin grant materialization from --admins)

Changes to grants and groups do not take effect until the snapshot is rebuilt.

Access Commands — CLI reference for grant, group, and token commands
CEL Expressions — full CEL syntax reference
swamp serve Architecture — why deny-wins, why default-deny, why hard refusals