API KEY SCOPING

Swamp provides two types of API keys — personal keys and collective tokens — because personal identity and collective identity serve different purposes.

Why two types exist

A personal API key is tied to your user account. When you authenticate with one, the system knows who you are — your username, your roles, your collective memberships. This is how the CLI works: swamp auth login creates a personal key, and every command you run executes as you.

A collective API token is tied to an organization, not a person. When you authenticate with one, the system knows which collective is acting — but not which person. The request is attributed to the collective itself.

The isolation boundary

This distinction is deliberate. The two key types are verified through entirely separate paths and grant different levels of access. A collective token cannot do anything a user can do — it can only do things the collective can do. And a personal key cannot impersonate a collective without the user actually being a member.

The boundary runs both ways, which is the point. Neither type can escalate into the other's scope.

When to use personal keys

Personal keys are the right choice for interactive work and personal automation:

• CLI usage — swamp auth login handles this automatically
• Personal scripts — a cron job that pushes your extensions, a bot that monitors your issues
• Development — local tooling that needs to call the Swamp API as you

The tradeoff is that personal keys carry your full permissions. If one leaks, the attacker operates as you across all your collectives.

When to use collective tokens

Collective tokens are the right choice for shared infrastructure:

• CI/CD pipelines — a GitHub Actions workflow that publishes extensions under the collective's namespace after tests pass
• Shared tooling — a deployment script that multiple team members run but that should authenticate as the team, not as whoever last logged in
• Service accounts — bots or integrations that act on behalf of the collective

The key advantage is personnel independence. If someone leaves the team and their personal key is revoked, the collective's CI pipeline keeps working. Collective tokens also make audit trails cleaner — actions show up as the collective, not as whichever team member happened to configure the pipeline.

The tradeoff is narrower scope. Collective tokens can only perform operations their granted scopes allow, and they are scoped to the single collective that created them.

Why team features require authentication

Some features — external datastores, non-local vaults, and swamp serve in token or oauth mode — require a swamp-club.com account even though the resources they manage live locally or in your own cloud infrastructure. The reason is that these features cross the boundary from single-machine use into shared team state. A local filesystem datastore and a local_encryption vault affect only the machine they live on, so there is no accountability requirement. But an S3 datastore, an AWS Secrets Manager vault, or a network-accessible serve instance affect resources that multiple team members rely on — and Swamp needs to know who is configuring them.

Collective token scopes follow a two-tier model. Categories where operations carry meaningfully different blast radii have fine-grained scopes — for example, extensions:push, extensions:promote, and extensions:read let a CI token follow least-privilege by granting only what the pipeline actually needs. Categories where the capability is binary — you either run a serve instance or you don't — use a single category-level wildcard like serve:*, datastore:*, or vault:*.

Each fine-grained category also supports a wildcard (extensions:*, lab:*, profile:*, etc.) that expands to all scopes within that category. This keeps broad tokens simple while letting teams that care about least-privilege narrow down to exactly the operations their workflow requires.

Personal keys carry all scopes implicitly because a personal key already represents a fully identified operative — the authentication is the accountability. Collective tokens require explicit scopes because they strip away the individual identity, so the scope declaration serves as an intentional statement of what the token is for.

Choosing between them

A useful rule of thumb: if the operation is something you are doing, use a personal key. If the operation is something the team is doing, use a collective token. When in doubt, start with your personal key via swamp auth login — you can always move to a collective token later when the workflow matures.