Manage teams via API

Create and manage teams programmatically using the Houston GraphQL 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.

Related documentation

• Import IdP groups
• Manage user permissions
• Houston API