Manage teams via API

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

mutation {
  createTeam(
    name: "Data Engineering"
    description: "Data engineering team"
    provider: "local"
    userIds: ["<user-uuid-1>", "<user-uuid-2>"]
  ) {
    team {
      id
      name
      provider
      description
      users {
        id
        username
      }
    }
    message
  }
}

Create IdP team

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

mutation {
  createTeam(
    name: "engineering-group"
    description: "Synced from Okta"
    provider: "okta"
  ) {
    team {
      id
      name
      provider
    }
    message
  }
}

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

mutation {
  updateTeam(
    id: "<team-uuid>"
    newName: "Platform Engineering"
    description: "Updated description"
  ) {
    team {
      id
      name
      description
    }
    message
  }
}

Add users to local team

mutation {
  updateTeam(
    id: "<team-uuid>"
    addUserIds: ["<user-uuid-3>", "<user-uuid-4>"]
  ) {
    team {
      id
      users {
        id
        username
      }
    }
  }
}

Remove users from local team

mutation {
  updateTeam(
    id: "<team-uuid>"
    removeUserIds: ["<user-uuid-1>"]
  ) {
    team {
      id
      users {
        id
        username
      }
    }
  }
}

Replace all users

mutation {
  updateTeam(
    id: "<team-uuid>"
    teamUserIds: ["<user-uuid-5>", "<user-uuid-6>"]
  ) {
    team {
      users {
        id
        username
      }
    }
  }
}

Update by name (alternative)

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

mutation {
  updateTeam(
    name: "Data Engineering"
    provider: "local"
    newName: "Data Platform"
  ) {
    team {
      id
      name
    }
  }
}

Remove a team

Remove by UUID

mutation {
  removeTeam(teamUuid: "<team-uuid>") {
    id
    name
  }
}

Remove by name and provider

mutation {
  removeTeam(
    name: "Data Engineering"
    provider: "local"
  ) {
    id
    name
  }
}

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

Query teams

Get single team

query {
  team(teamUuid: "<team-uuid>") {
    id
    name
    provider
    description
    createdAt
    updatedAt
    users {
      id
      username
      emails {
        address
      }
    }
    roleBindings {
      role
      workspace {
        id
        label
      }
      deployment {
        id
        label
      }
    }
  }
}

List teams with search

searchPhrase requires a minimum of three characters.

query {
  paginatedTeams(
    take: 20
    pageNumber: 1
    searchPhrase: "engineering"
  ) {
    teams {
      id
      name
      provider
      users {
        id
      }
    }
    count
  }
}

List workspace teams

query {
  workspaceTeams(workspaceUuid: "<workspace-uuid>") {
    id
    name
    roleBindings {
      role
    }
  }
}

List deployment teams

query {
  deploymentTeams(deploymentUuid: "<deployment-uuid>") {
    id
    name
    roleBindings {
      role
    }
  }
}

Assign team roles

Add team to workspace

If you omit role, the team defaults to WORKSPACE_VIEWER.

mutation {
  workspaceAddTeam(
    teamUuid: "<team-uuid>"
    workspaceUuid: "<workspace-uuid>"
    role: WORKSPACE_EDITOR
  ) {
    id
    label
  }
}

Add team with deployment roles

Assign workspace and deployment roles in a single mutation:

mutation {
  workspaceAddTeam(
    teamUuid: "<team-uuid>"
    workspaceUuid: "<workspace-uuid>"
    role: WORKSPACE_VIEWER
    deploymentRoles: [
      { deploymentId: "<deployment-uuid-1>", role: DEPLOYMENT_ADMIN }
      { deploymentId: "<deployment-uuid-2>", role: DEPLOYMENT_EDITOR }
    ]
  ) {
    id
  }
}

Update team workspace role

mutation {
  workspaceUpdateTeamRole(
    teamUuid: "<team-uuid>"
    workspaceUuid: "<workspace-uuid>"
    role: WORKSPACE_ADMIN
  )
}

Remove team from workspace

mutation {
  workspaceRemoveTeam(
    teamUuid: "<team-uuid>"
    workspaceUuid: "<workspace-uuid>"
  ) {
    id
  }
}

Add team to deployment

mutation {
  deploymentAddTeamRole(
    teamUuid: "<team-uuid>"
    deploymentUuid: "<deployment-uuid>"
    role: DEPLOYMENT_EDITOR
  ) {
    id
    role
  }
}

Update team deployment role

mutation {
  deploymentUpdateTeamRole(
    teamUuid: "<team-uuid>"
    deploymentUuid: "<deployment-uuid>"
    role: DEPLOYMENT_ADMIN
  ) {
    id
    role
  }
}

Remove team from deployment

mutation {
  deploymentRemoveTeamRole(
    teamUuid: "<team-uuid>"
    deploymentUuid: "<deployment-uuid>"
  ) {
    id
  }
}

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

auth:
  local:
    teams:
      enabled: true

Enable IdP group sync

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

auth:
  openidConnect:
    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.

​Prerequisites

​Team types

​Create a team

​Create local team

​Create IdP team

​Parameters

​Update a team

​Update team details

​Add users to local team

​Remove users from local team

​Replace all users

​Update by name (alternative)

​Remove a team

​Remove by UUID

​Remove by name and provider

​Query teams

​Get single team

​List teams with search

​List workspace teams

​List deployment teams

​Assign team roles

​Add team to workspace

​Add team with deployment roles

​Update team workspace role

​Remove team from workspace

​Add team to deployment

​Update team deployment role

​Remove team from deployment

​Available roles

​Workspace roles

​Deployment roles

​Configuration

​Enable local teams

​Enable IdP group sync

​Error handling

​Best practices

​Related documentation

Prerequisites

Team types

Create a team

Create local team

Create IdP team

Parameters

Update a team

Update team details

Add users to local team

Remove users from local team

Replace all users

Update by name (alternative)

Remove a team

Remove by UUID

Remove by name and provider

Query teams

Get single team

List teams with search

List workspace teams

List deployment teams

Assign team roles

Add team to workspace

Add team with deployment roles

Update team workspace role

Remove team from workspace

Add team to deployment

Update team deployment role

Remove team from deployment

Available roles

Workspace roles

Deployment roles

Configuration

Enable local teams

Enable IdP group sync

Error handling

Best practices

Related documentation