Skip to main content

Teams & Permissions

A team is a named group of organization members that gets shared access to one or more projects. Teams are how you say "the backend group can edit secrets on the API project; the frontend group is read-only."

The permission model​

Each team grants a set of per-project permissions. The same four booleans apply everywhere access is granted (teams, service tokens):

PermissionWhat it allows
can_readView the project, its services, secrets metadata (names only — never values), deployments, logs. On by default when a project is added to a team.
can_change_gws_configsEdit gws.json, services, profiles, watch configuration. Required for gws config import.
can_change_secretsCreate, update, and delete secrets. Values are still write-only — no one ever reads them back.
can_delete_projectDelete the project and everything it owns. Use sparingly.

The four flags are independent — you can grant can_change_secrets without can_change_gws_configs, or vice versa.

Create a team​

  1. Open Organizations → <your org> → Teams.
  2. Click Create team, give it a name (e.g. backend, frontend, devops).
  3. The team is created empty; you'll add members and projects next.

Add members to a team​

  1. Open the team.
  2. Members sub-tab → Add member.
  3. Pick from the active org members (you can only add people who are already in the organization — see Inviting Members).

A user can be on multiple teams. Their effective per-project permissions are the union of all teams that grant access to that project — i.e. permissions are additive, not overridden.

Grant project access​

  1. Open the team.
  2. Projects sub-tab → Add project.
  3. Pick a project in the organization and tick the permissions to grant. can_read is the default; the others are off until you opt in.

To revoke access, remove the project from the team. To change permissions, edit the row.

Recipes​

Read-only auditor team​

can_read:                ✓ (default)
can_change_gws_configs:  ✗
can_change_secrets:      ✗
can_delete_project:      ✗

Useful for security or compliance roles that need to see deployments and config but not change anything.

App developers​

can_read:                ✓
can_change_gws_configs:  ✓
can_change_secrets:      ✗
can_delete_project:      ✗

Devs can iterate on services, profiles, and watch config — but can't rotate production secrets.

DevOps / on-call​

can_read:                ✓
can_change_gws_configs:  ✓
can_change_secrets:      ✓
can_delete_project:      ✗

Full operational access without the foot-gun of accidental project deletion.

Project lead​

can_read:                ✓
can_change_gws_configs:  ✓
can_change_secrets:      ✓
can_delete_project:      ✓

Total ownership of a single project. Combine with org member role to keep blast radius small.

What the CLI sees​

The CLI authenticates as a user, so it inherits whatever permissions the user's teams grant on each project. If gws secret set returns 403, it usually means a team is missing can_change_secrets for the project.

For CI and AI agents that should not be tied to a person, mint a service token with the exact permission set you want, scoped to one project.

Next​