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 cannot perform user-level operations like submitting issues or managing personal settings. They are scoped to the single collective that created them.

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.