> ## Documentation Index
> Fetch the complete documentation index at: https://astronomer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage user permissions on Astro Private Cloud

Astro Private Cloud supports a permissions and role-based access control (RBAC) framework that allows users to configure varying levels of access both at the Workspace and Airflow Deployment levels.

Workspace and Deployment-level access can each be configured with three user roles (*Admin*, *Editor*, *Viewer*), all of which can be set and changed via the Astro Private Cloud UI and CLI. Each role maps to a combination of permissions for both Astro Private Cloud and Apache Airflow itself.

This guide includes:

1. How to invite users to an Astro Private Cloud Workspace and Deployment
2. How to view, set, and modify user roles
3. Deployment and Workspace Permissions Reference

## Invite users

Workspace and Deployment Admins can invite and otherwise manage users both via the Astro Private Cloud UI and CLI. All users who have access to a Workspace must be assigned one of three Workspace roles, though Deployment-level roles are not required.

Read below for guidelines.

### Invite to Workspace

The ability to invite users to an Astronomer Workspace is limited to Workspace Admins, who can also grant the Admin role to other users. Workspace Editors and Viewers cannot invite or otherwise manage other Workspace users, though they may do so at the Deployment level depending on their Deployment-level role.

A user who creates a Workspace is automatically granted the Admin role for the Workspace and has the ability to create any number of Airflow Deployments within it. Every Workspace must have at least one Workspace Admin.

#### Using the Astro Private Cloud UI

To invite a user to a Workspace via the Astro Private Cloud UI, select your Workspace from the Workspace list dropdown on the side navigation bar and navigate to **Workspace Settings** > **Users** > **Invite User**.

When a Workspace Admin invites a user to a Workspace in which one or more Airflow Deployments exist, they'll have the opportunity to set that user's Deployment-level roles as well, though it is not required.

If a Workspace Admin invites a user to a Workspace that has no Airflow Deployments, the **Deployment Roles** modal will not appear.

#### Using the Astro CLI

To invite a user to a Workspace using the Astro CLI, run:

```bash wrap theme={null}
astro workspace user add <email-address> --workspace-id <workspace-id> --role <workspace-role>
```

Only Workspace *Admins* can invite other users and set their permissions.

To find **Workspace ID**, you can:

* Run `$ astro workspace list`
* Find it in the Workspace URL from your browser after the `/w/` (e.g. `https://app.basedomain/w/<workspace-id>`)

To set a **Role**, add a flag in the following format:

* `--WORKSPACE_EDITOR`
* `--WORKSPACE_VIEWER`
* `--WORKSPACE_ADMIN`

If you do *not* specify a role in this command, `WORKSPACE_VIEWER` will be set by default. In all cases where a user is invited to a Workspace and Deployment-level role is not specified, no Deployment-level role will be assumed.

#### Using Teams

You can invite a group of users from a configured third party identity provider (IdP) as a Team to your Workspace. A Team is an IdP-defined group of users who all share the same permissions to a given Deployment or Workspace.

Note that to use Teams, a System Admin must first complete the setup in [Integrate an auth system](/docs/astro-private-cloud/v-1-x/integrate-auth-system) and configure user groups as described in [Import IdP Groups](/docs/astro-private-cloud/v-1-x/import-idp-groups).

To add a Team to a Workspace:

1. In the Control Plane UI, go to your **Workspace Settings** page and open the **Teams** tab.

2. Click **+Team**.

3. Under **Team Name**, enter the name of your IdP group.

4. Select a **Workspace Role** for the Team. If your Workspace has existing Deployments, you can also configure the Team's permissions to those Deployments on this page:

   <Frame>
     <img src="https://mintcdn.com/astronomer/Ct4jHNJYwyny9aUD/images/astro-private-cloud/add-team-workspace.png?fit=max&auto=format&n=Ct4jHNJYwyny9aUD&q=85&s=5bf42ec8f00b41c6681dba618a5e58a9" alt="Screen for adding a Team to a Workspace" width="3440" height="1722" data-path="images/astro-private-cloud/add-team-workspace.png" />
   </Frame>

5. Click **Add**.

<Warning>If a user already exists on a Workspace before being invited via a Team, the user context with the most permissive role will be applied to the Workspace. For more information, read [Import IdP Groups](/docs/astro-private-cloud/v-1-x/import-idp-groups).</Warning>

### Invite to Deployment

The ability to invite Workspace users to an Airflow Deployment within it is limited to Deployment *Admins*, who can also grant the *Admin* role to other users. Deployment *Editors* and *Viewers* cannot invite or otherwise manage users. A user who creates a Deployment is automatically granted the *Admin* role within it.

<Note>
  In order for a user to be granted access to an Airflow Deployment, they must *first* be invited to and assigned a role within the Workspace. A user can be a part of a Workspace but have no access or role to any Airflow Deployments within it.
</Note>

#### Using the Astro Private Cloud UI

To invite a Workspace user to an Airflow Deployment via the Astro Private Cloud UI:

1. Select your **Workspace** and then navigate to **Deployment** > **Users**.
2. Type the Workspace user's name in the search bar on top or click **Show All** to view all users.
3. Select a Deployment role from the drop-down menu to the right of the selected user.
4. Click the `+` symbol.

#### Using the Astro CLI

To invite a Workspace user to an Airflow Deployment using the Astro CLI, run:

```text wrap theme={null}
astro deployment user add --email=<email-address> --deployment-id=<deployment-id> --role=<deployment-role>
```

Only Deployment *Admins* can invite other users and set their permissions.

To find **Deployment ID**, you can:

* Run `$ astro deployment list`

To set a **Role**, add a flag in the following format:

* `--DEPLOYMENT_EDITOR`
* `--DEPLOYMENT_VIEWER`
* `--DEPLOYMENT_ADMIN`

If you do *not* specify a role in this command, `DEPLOYMENT_VIEWER` will be set by default.

#### Using Teams

You can invite a group of users from a configured third party identity provider (IdP) as a Team on your Deployment. A Team is an IdP-defined group of users who all share the same permissions to a given Deployment or Workspace.

Note that to use Teams, a System Admin must first complete the setup in [Integrate an auth system](/docs/astro-private-cloud/v-1-x/integrate-auth-system) and configure user groups as described in [Import IdP Groups](/docs/astro-private-cloud/v-1-x/import-idp-groups).

To add a team to a Deployment:

1. In the Control Plane UI, go to your Deployment and open the **Teams** tab.
2. In the search bar that appears, search for your Team's name.
3. When your Team appears, select a Deployment-level role for the Team and click the **+** button:

   <Frame>
     <img src="https://mintcdn.com/astronomer/Ct4jHNJYwyny9aUD/images/astro-private-cloud/add-team-deployment.png?fit=max&auto=format&n=Ct4jHNJYwyny9aUD&q=85&s=3487b781e9aeeb65f466ea4ed804aacb" alt="Screen for adding a Team to a Deployment" width="3444" height="1722" data-path="images/astro-private-cloud/add-team-deployment.png" />
   </Frame>

<Warning>If a user already exists on a Deployment before being invited via a Team, the user context with the most permissive role will be applied to the Deployment. For more information, read [Import IdP Groups](/docs/astro-private-cloud/v-1-x/import-idp-groups).</Warning>

## View and edit user roles

### Workspace

#### View Workspace users

To view roles within a Workspace via the Astro Private Cloud UI, select your Workspace from the left sidebar and navigate to **Workspace Settings** > **Users**. All Workspace users have access to this view and can see the roles of other users.

To list Workspace users using the Astro CLI, run:

```bash wrap theme={null}
astro workspace user list
```

This command will output the email addresses of all users in the Workspace alongside their ID and Workspace Role.

#### Edit Workspace user role

If you're a Workspace *Admin*, you can edit both Workspace and Deployment-level permissions by selecting your Workspace from the left sidebar and navigating to **Workspace Settings** > **Users** and clicking into an individual user.

To edit a user's role using the Astro CLI, run:

```bash wrap theme={null}
astro workspace user update <email> --workspace-id=<workspace-id> --role=<workspace-role>
```

Only Workspace *Admins* can modify the role of another user in the Workspace.

#### Remove Workspace user

Workspace *Admins* can remove users from a Workspace by selecting your Workspace from the left sidebar and navigating to: **Workspace Settings** > **Users** > **Individual User** > **Remove User**.

<Frame>
  <img src="https://mintcdn.com/astronomer/Ct4jHNJYwyny9aUD/images/astro-private-cloud/remove-workspace-user.png?fit=max&auto=format&n=Ct4jHNJYwyny9aUD&q=85&s=6e2e6cc237e7e1ec77629f53658c25df" alt="Remove Workspace User" width="3431" height="1713" data-path="images/astro-private-cloud/remove-workspace-user.png" />
</Frame>

To remove a user from a Workspace via the Astro CLI, make sure you're first operating in that Workspace. Then, run:

```bash wrap theme={null}
astro workspace user remove <email>
```

Only Workspace *Admins* can remove other Workspace users.

### Deployment

#### View Deployment users

To list all users within a Deployment and their corresponding roles, select your Workspace from the left sidebar and navigate to **Deployments** > **Individual Deployment** > **Users**. All Deployment users have access to this view and can see the roles of other users.

To list Deployment users via the Astro CLI, run:

```bash wrap theme={null}
astro deployment user list --deployment-id=<deployment-id>
```

#### Edit Deployment user role

Deployment *Admins* can edit permissions using the dropdown menu in the **Access** tab in the Astro Private Cloud UI.

To edit a user's role using the Astro CLI, run:

```bash wrap theme={null}
astro deployment user update <email> --deployment-id=<deployment-id> --role=<deployment-role>
```

<Note>
  A Deployment-level role cannot be edited while a Workspace invitation to that user is pending. If you invite a user to a Workspace, you will not be able to modify their permissions until they accept the Workspace invite.
</Note>

#### Remove Deployment user

To delete a user from an Airflow Deployment via the Astro Private Cloud UI, Deployment *Admins* can click on the wastebasket icon within the **Access** tab shown in the screenshot above.

To delete a user from an Airflow Deployment using the Astro CLI, run:

```bash wrap theme={null}
astro deployment user remove <email> --deployment-id=<deployment-id>
```

## User permissions reference

### Deployment

#### Deployment Viewer

Deployment *Viewers* are limited to read-only mode. They can only:

* View Deployment users
* View the **Metrics** and **Logs** tabs of the Astro Private Cloud UI
* View information about Dags and tasks in the Airflow UI

Deployment Viewers cannot deploy to, modify, or delete anything within an Airflow Deployment. Additionally, they cannot create or use service accounts to do so. Attempts to modify a Deployment in any way will result in a `403` and an `Access is Denied` message.

<Frame>
  <img src="https://mintcdn.com/astronomer/XZk5DsNifaMN7o1r/images/software/access_denied.png?fit=max&auto=format&n=XZk5DsNifaMN7o1r&q=85&s=bd6efe0fb2d93d893e9e4d14d908d0bc" alt="Access Denied" width="1267" height="279" data-path="images/software/access_denied.png" />
</Frame>

#### Deployment Editor

With fewer permissions than *Admins*, a Deployment *Editor*:

* Can access and make changes to the Deployment on Astronomer, such as modify resources, add environment variables, or push code
* Cannot delete the Deployment
* Can perform CRUD operations on any service account in the Deployment
* Cannot manage other users in the Deployment
* Has full access to modify and interact with Dags in the Airflow UI
* Does NOT have access to the **Admin** menu in Airflow, which includes:
  * Pools
  * Configuration
  * Users
  * Connections
  * Variables
  * XComs

<Frame>
  <img src="https://mintcdn.com/astronomer/XZk5DsNifaMN7o1r/images/software/editor_view.png?fit=max&auto=format&n=XZk5DsNifaMN7o1r&q=85&s=0d8dbb44bb126fbcd97a57e460394fde" alt="No Admin Tab" width="1115" height="259" data-path="images/software/editor_view.png" />
</Frame>

#### Deployment Admin

Deployment *Admins* are the highest-tiered role. Admins:

* Can perform CRUD (create, read, update, delete) Astronomer operations on the Deployments, such as modify resources, add environment variables, push code, or delete the Deployment
* Can manage users and their permissions in the Deployment
* Can perform CRUD operations on any service account in the Workspace
* Can perform CRUD Airflow operations (push code, add Connections, clear tasks, delete Dags etc.)
* Have full access to the **Admin** menu in the Airflow UI
* Have full access to modify and interact with Dags in the Airflow UI

Every Deployment must have at least one Deployment *Admin*.

### Workspace

#### Workspace Viewer

A Workspace *Viewer* is limited to read-only mode. *Viewers*:

* Can list users in a Workspace
* Can view all service accounts in the Workspace
* Cannot delete or modify the Workspace or its users

<Note>
  If a role is not set, newly invited users are Workspace *Viewers* by default.
</Note>

#### Workspace Editor

Below a Workspace *Admin*, an *Editor*:

* Can access and make changes to the Workspace in the **Settings** tab
* Can perform CRUD operations on any service account in the Workspace
* Can create Airflow Deployments in the Workspace
* Cannot manage other users in the Workspace
* Cannot delete the Workspace

#### Workspace Admin

Workspace *Admins* are the highest-tiered role at the Workspace level. Admins:

* Can manage users and their permissions in a Workspace.
* Can perform CRUD (create, read, update, delete) operations on the Workspace (e.g. delete the Workspace, change its name).
* Can create Airflow Deployments in the Workspace.
* Can perform CRUD operations on any Airflow Deployment within the Workspace.
* Can perform CRUD operations on any service account in the Workspace.

Every Workspace must have at least one Workspace *Admin*.

A Workspace *Admin* always has these permissions for any Deployment in the Workspace. Even if a Workspace Admin also has a defined role with lower permissions like Deployment *Viewer*, Astronomer uses the permissions configured for the user at the Workspace level.

## System Roles

### System Viewer

System *Viewers* have read-only access across the entire platform. They:

* Can view the Airflow UI and configuration for any Deployment
* Can view environment variables and settings for any Deployment
* Can view all Workspaces, users, and service accounts
* Can view system monitoring dashboards
* Can view pending user invites and the current Astronomer release version

***

### System Editor

System *Editors* have write access to most configurations but not full admin control. They:

* Inherit all System Viewer permissions
* Can modify environment variables and IAM roles for any Deployment
* Can create, update, and delete service accounts for any Workspace or Deployment
* Can view system admin users
* Can push or modify base Docker images used by Airflow

***

### System Admin

System *Admins* have complete administrative access across the Astronomer platform. They:

* Inherit all System Viewer and Editor permissions
* Can create, modify, or delete any Deployment or Workspace
* Can manage all users, roles, and service accounts globally
* Can view and manage logs and metrics for all Deployments
* Can push images and deploy code to any Deployment
* Can invite, delete, or force-delete users (including IdP-managed users)
* Can manually verify user emails
* Can perform system-level Airflow administration (pools, connections, variables, etc.)
* Can perform system cleanup operations (for example, purge Airflow metadata)

## What's next

As an Astro Private Cloud user, you can customize all user permissions at the platform-level. For more information, read:

* [Manage Users on Astro Private Cloud](/docs/astro-private-cloud/v-1-x/manage-platform-users#customize-role-permissions)
* [Integrate an auth system](/docs/astro-private-cloud/v-1-x/integrate-auth-system)