Manage teams via API | Astronomer Documentation

Teams in Astro Private Cloud let you group users and assign permissions collectively. You can manage teams locally or sync them from an Identity Provider (IdP). To configure IdP group sync, see Import identity provider (IdP) groups.

Prerequisites

Access to the Houston GraphQL API endpoint for your Astro Private Cloud installation.
A valid authentication token. See Authenticate to the Houston API.
The UUIDs of any users, workspaces, or Deployments you want to reference.

Team types

Type	Provider	User Management	Use Case
Local teams	`local`	Manual add/remove	Local authentication, custom groupings
IdP teams	`okta`, `auth0`, `microsoft`, `ida`, `adfs`	Auto-synced from IdP	Enterprise SSO integration

Create a team

Create local team

1 mutation {
2   createTeam(
3     name: "Data Engineering"
4     description: "Data engineering team"
5     provider: "local"
6     userIds: ["<user-uuid-1>", "<user-uuid-2>"]
7   ) {
8     team {
9       id
10       name
11       provider
12       description
13       users {
14         id
15         username
16       }
17     }
18     message
19   }
20 }

Create IdP team

IdP group sync automatically creates IdP teams, but you can also create them manually:

1 mutation {
2   createTeam(
3     name: "engineering-group"
4     description: "Synced from Okta"
5     provider: "okta"
6   ) {
7     team {
8       id
9       name
10       provider
11     }
12     message
13   }
14 }

You can’t assign users to IdP teams at creation time. The IdP syncs users to the team.

Parameters

Parameter	Type	Required	Description
`name`	String	Yes	Team name (unique per provider)
`description`	String	No	Team description
`provider`	String	No	`local` (default), `okta`, `auth0`, `microsoft`, `ida`, `adfs`
`userIds`	[ID]	No	User UUIDs (local teams only)

Update a team

Update team details

1 mutation {
2   updateTeam(
3     id: "<team-uuid>"
4     newName: "Platform Engineering"
5     description: "Updated description"
6   ) {
7     team {
8       id
9       name
10       description
11     }
12     message
13   }
14 }

Add users to local team

1 mutation {
2   updateTeam(
3     id: "<team-uuid>"
4     addUserIds: ["<user-uuid-3>", "<user-uuid-4>"]
5   ) {
6     team {
7       id
8       users {
9         id
10         username
11       }
12     }
13   }
14 }

Remove users from local team

1 mutation {
2   updateTeam(
3     id: "<team-uuid>"
4     removeUserIds: ["<user-uuid-1>"]
5   ) {
6     team {
7       id
8       users {
9         id
10         username
11       }
12     }
13   }
14 }

Replace all users

1 mutation {
2   updateTeam(
3     id: "<team-uuid>"
4     teamUserIds: ["<user-uuid-5>", "<user-uuid-6>"]
5   ) {
6     team {
7       users {
8         id
9         username
10       }
11     }
12   }
13 }

Update by name (alternative)

Team names are unique per provider, not globally. You must include provider alongside name to uniquely identify a team.

1 mutation {
2   updateTeam(
3     name: "Data Engineering"
4     provider: "local"
5     newName: "Data Platform"
6   ) {
7     team {
8       id
9       name
10     }
11   }
12 }

Remove a team

Remove by UUID

1 mutation {
2   removeTeam(teamUuid: "<team-uuid>") {
3     id
4     name
5   }
6 }

Remove by name and provider

1 mutation {
2   removeTeam(
3     name: "Data Engineering"
4     provider: "local"
5   ) {
6     id
7     name
8   }
9 }

You can only remove IdP teams that have no attached users.

Query teams

Get single team

1 query {
2   team(teamUuid: "<team-uuid>") {
3     id
4     name
5     provider
6     description
7     createdAt
8     updatedAt
9     users {
10       id
11       username
12       emails {
13         address
14       }
15     }
16     roleBindings {
17       role
18       workspace {
19         id
20         label
21       }
22       deployment {
23         id
24         label
25       }
26     }
27   }
28 }

List teams with search

searchPhrase requires a minimum of three characters.

1 query {
2   paginatedTeams(
3     take: 20
4     pageNumber: 1
5     searchPhrase: "engineering"
6   ) {
7     teams {
8       id
9       name
10       provider
11       users {
12         id
13       }
14     }
15     count
16   }
17 }

List workspace teams

1 query {
2   workspaceTeams(workspaceUuid: "<workspace-uuid>") {
3     id
4     name
5     roleBindings {
6       role
7     }
8   }
9 }

List deployment teams

1 query {
2   deploymentTeams(deploymentUuid: "<deployment-uuid>") {
3     id
4     name
5     roleBindings {
6       role
7     }
8   }
9 }

Assign team roles

Add team to workspace

If you omit role, the team defaults to WORKSPACE_VIEWER.

1 mutation {
2   workspaceAddTeam(
3     teamUuid: "<team-uuid>"
4     workspaceUuid: "<workspace-uuid>"
5     role: WORKSPACE_EDITOR
6   ) {
7     id
8     label
9   }
10 }

Add team with deployment roles

Assign workspace and deployment roles in a single mutation:

1 mutation {
2   workspaceAddTeam(
3     teamUuid: "<team-uuid>"
4     workspaceUuid: "<workspace-uuid>"
5     role: WORKSPACE_VIEWER
6     deploymentRoles: [
7       { deploymentId: "<deployment-uuid-1>", role: DEPLOYMENT_ADMIN }
8       { deploymentId: "<deployment-uuid-2>", role: DEPLOYMENT_EDITOR }
9     ]
10   ) {
11     id
12   }
13 }

Update team workspace role

1 mutation {
2   workspaceUpdateTeamRole(
3     teamUuid: "<team-uuid>"
4     workspaceUuid: "<workspace-uuid>"
5     role: WORKSPACE_ADMIN
6   )
7 }

Remove team from workspace

1 mutation {
2   workspaceRemoveTeam(
3     teamUuid: "<team-uuid>"
4     workspaceUuid: "<workspace-uuid>"
5   ) {
6     id
7   }
8 }

Add team to deployment

1 mutation {
2   deploymentAddTeamRole(
3     teamUuid: "<team-uuid>"
4     deploymentUuid: "<deployment-uuid>"
5     role: DEPLOYMENT_EDITOR
6   ) {
7     id
8     role
9   }
10 }

Update team deployment role

1 mutation {
2   deploymentUpdateTeamRole(
3     teamUuid: "<team-uuid>"
4     deploymentUuid: "<deployment-uuid>"
5     role: DEPLOYMENT_ADMIN
6   ) {
7     id
8     role
9   }
10 }

Remove team from deployment

1 mutation {
2   deploymentRemoveTeamRole(
3     teamUuid: "<team-uuid>"
4     deploymentUuid: "<deployment-uuid>"
5   ) {
6     id
7   }
8 }

Available roles

Workspace roles

Role	Permissions
`WORKSPACE_ADMIN`	Full Workspace control, manage users/teams
`WORKSPACE_EDITOR`	Create/manage Deployments, service accounts
`WORKSPACE_VIEWER`	View Workspace and Deployment details

Deployment roles

Role	Permissions
`DEPLOYMENT_ADMIN`	Full Deployment control, manage access
`DEPLOYMENT_EDITOR`	Deploy code, manage configuration
`DEPLOYMENT_VIEWER`	View Deployment details

Configuration

Enable local teams

1 auth:
2   local:
3     teams:
4       enabled: true

Enable IdP group sync

For full setup instructions, see Import identity provider (IdP) groups.

1 auth:
2   openidConnect:
3     idpGroupsImportEnabled: true

Error handling

Error	Cause	Resolution
`LocalTeamManagementDisabledError`	Local teams not enabled	Enable in Helm values
`IDPTeamManagementDisabledError`	IdP groups import disabled	Enable IdP group sync
`DuplicateTeamError`	Team name exists for provider	Use unique name
`DuplicateRoleBindingError`	Team already has role	Update existing role instead
`InvalidTeamProviderError`	Unsupported provider value	Use `local`, `okta`, `auth0`, `microsoft`, `ida`, or `adfs`
`ResourceNotFoundError`	Team/user not found	Verify UUIDs

Best practices

Use IdP teams for enterprise SSO environments.
Use local teams for custom access groups.
Assign Workspace roles before Deployment roles.
Use Viewer roles as default and escalate as needed.
Audit team membership regularly.