Skip to main content
This is feature is only available if you are on the Team tier or above. See Astro Plans and Pricing.
Team plans are limited to two Teams, but Business plans allow you to have unlimited Teams. See pricing.
As an Organization Owner or Workspace Owner, you can use Teams to batch assign Organization and Workspace roles to groups of users. Organization Owners create, update, or delete Teams. Then, either Organization Owners or Workspace Owners can assign Teams to different Workspaces and define their Workspace permissions. For Deployments running Astro Runtime 3.1-12 or later, you can also assign Teams to individual Dags with Dag-specific roles. See Dag-level access control. A Team is a group of users in an Organization that share the same Organization and Workspace permissions. You can use Teams to securely assign permissions for a large group of users across multiple Workspaces. For example, you can create a Team of dag authors, then assign that Team to each of your development Workspaces as a Workspace author. You can also assign different roles for each Workspace. For example, you can have a group of dag authors that has full Workspace Owner permissions for development Workspaces, and that same Team can have only Workspace Member permissions for production Workspaces.
A new Astro UI is hereAstronomer has redesigned the Astro UI. Try the new experience and switch your instructions using the New Astro UI and Legacy UI tabs on this page. Your selection is remembered across the docs.

​
Create a Team

  1. In the Astro UI, go to Settings, then in the Access Management section, click Teams.
  2. Click + New Team.
  3. In the New Team panel, enter a Team Name and Team Description, select an Organization Role, and optionally Add Users. If you can’t find a user, you might need to add them to your Organization first.
  4. Click Create Team.
You can now add your Team to a Workspace and define the Team users’ permissions in the Workspace.

​
Update existing Teams

  1. In the Astro UI, go to Settings, then in the Access Management section, click Teams.
  2. Click a Team to open its detail page. The Members tab is selected by default.
  3. To add a member, click + Add Member, use the Add Users dropdown to find the user, then click Add Members.
  4. To remove a member, hover over their row and click the trash icon.

​
Add a Team to a Workspace

  1. In the Astro UI, go to Settings > Workspaces.
  2. Select your Workspace, then go to Access Management > Teams.
  3. Click + Add Team.
  4. Select the Team you want to add and define their Workspace Role, which determines their Workspace user permissions.
Centralized access management for Organization OwnersOrganization Owners can also add or update a Team for a Workspace from your Organization’s access management settings:
  1. In the Astro UI, go to Settings, then in the Access Management section, click Teams.
  2. Select the Team.
  3. Click the Workspaces tab, then click + Add Workspace to add them to a Workspace, or Edit Role to change their role for an existing Workspace.
CLIYou can add a Team to multiple Workspaces programmatically using the Astro CLI. See astro workspace team add for example output and commands.

​
Add a Team to a Dag

You can assign a Team to specific Dags within a Deployment, giving all Team members the same Dag-level permissions. For complete instructions, see Assign Dag roles to Teams.

​
Add a Team to multiple Workspaces using the Astro CLI

You can use the Astro CLI and a shell script to add a Team to multiple Workspaces at once. The shell script reads from a text file which contains Team information. You can generate a text file for each Team that needs to be assigned to Workspaces and run a script to process the file. You must have Organization Owner or Workspace Owner level permissions to add Teams to Workspaces.
  1. Create a text file named teams.txt.
  2. Open the text file. On each line, add a Team ID, the Team’s role, and the Workspace ID delimited by spaces. Your text file should look similar to the following:
  3. Create a file named add-teams.sh and add the following script to it:
    add-teams.sh
  4. (Optional) Log in to the Astro CLI using astro login, then run astro workspace list to ensure that you have access to the Workspaces where you want to add the users.
  5. Run the following command to execute the shell script:
  6. (Optional) To use this script as part of a CI/CD pipeline, create an Organization API token and specify the following environment variable in your CI/CD environment:
    • Key: ASTRO_API_TOKEN
    • Value: <your-api-token>

​
Teams and SCIM provisioning

To preserve a single source of truth for user group management, some Team management actions are limited when you set up SCIM provisioning. Specifically, when you set up SCIM provisioning:
  • You can’t create new Teams.
  • You can’t add users to existing Teams.
For any Teams that were created before you set up SCIM provisioning, you can still complete the following actions:
  • Update the Team’s permissions.
  • Remove users from the Team.
  • Delete the Team.