Teams

The Pulumi Cloud offers role-based access control (RBAC) using teams. Teams allow organization admins to assign a set of stack permissions to a group of users. When your organization has custom roles enabled, teams can also be assigned roles (in addition to stack-level permissions), so that members receive the union of the team’s roles and their own user role.

Creating a Team

By default, all organization admins can create new teams.

To create a team:

1. Navigate to Settings > Teams.
2. Select Create team.

Team Access Types

Members of a team can be granted Team admin or Team member permissions. Team admins can add members to a team. By default, any new team members will be assigned the team member role.

To change a team member’s role:

1. Navigate to Settings > Teams and then the specific team.
2. In the Members section use the action menu item at the end of the table row and select Change role to.

Role assignments

When your organization has custom roles enabled, teams can be assigned roles (default or custom). This is separate from Team entity access grants (stack-level access) and Team access types (Team admin vs Team member).

• Each team can have multiple role assignments. Members of the team receive the permissions from all of those roles in addition to their own organization role.
• To add or remove role assignments for a team, a user must hold a role that grants the role:update and team:update scopes — for example, an organization admin. Being a team admin is not sufficient on its own; a team admin without role:update access cannot modify role assignments. Team admins can, however, always manage the team’s Entity Access grants directly, regardless of their role scopes.
• Role-backed teams: Create a team, assign it a custom role (e.g. with access only to certain stacks or tag-based rules), then add members; those members gain the team’s roles in addition to their own user role.

To manage role assignments for a team, navigate to the team’s Access tab. The Role assignments section lists the roles currently assigned to the team; use Add role to assign an additional role.

.

GitHub-based Teams

If your Pulumi organization is backed by GitHub, you can import your existing GitHub teams into Pulumi.

For these teams, membership is managed on GitHub, while the set of stack permissions and role assignments granted to team members is managed in the Pulumi Cloud.

Team Entity Access Grants

Team entity access grants allow team admins to manage their team’s access to specific stacks, environments, and insights accounts directly, without requiring org-level role management permissions. This makes it possible for teams to self-manage their own entity access while keeping broader role administration centralized.

Teams can be granted direct access to stacks, environments, and insights accounts. All team members receive access to those entities at the selected permission level.

Managing environment access via the REST API

Team environment grants can also be managed programmatically using the Pulumi Cloud REST API. This is useful for automated provisioning workflows where team permissions need to be applied consistently across many environments or as part of a broader infrastructure-as-code setup.

All three operations — adding, editing, and removing an environment permission — use the same endpoint:

PATCH https://api.pulumi.com/api/orgs/{orgName}/teams/{teamName}
Authorization: token {token}
Content-Type: application/json

Add an environment permission:

curl -s -X PATCH \
  "https://api.pulumi.com/api/orgs/{orgName}/teams/{teamName}" \
  -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "addEnvironmentPermission": {
      "projectName": "{projectName}",
      "envName": "{envName}",
      "permission": "read"
    }
  }'

Or equivalently using the pulumi cloud api command:

pulumi cloud api PATCH \
  /orgs/{orgName}/teams/{teamName} \
  -- --body '{"addEnvironmentPermission":{"projectName":"{projectName}","envName":"{envName}","permission":"read"}}'

The valid permission values are:

Edit an existing environment permission:

curl -s -X PATCH \
  "https://api.pulumi.com/api/orgs/{orgName}/teams/{teamName}" \
  -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "editEnvironmentPermission": {
      "projectName": "{projectName}",
      "envName": "{envName}",
      "permission": "write"
    }
  }'

Remove an environment permission:

curl -s -X PATCH \
  "https://api.pulumi.com/api/orgs/{orgName}/teams/{teamName}" \
  -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "removeEnvironment": {
      "projectName": "{projectName}",
      "envName": "{envName}"
    }
  }'

The endpoint returns 204 No Content on success. These operations require a Pulumi access token scoped to a user with team administration rights; organization admins always have this access. The projectName field refers to the ESC project in which the environment resides — this is the project specified when the environment was created (for example, default if no explicit project was given).