> ## 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.

# Dag-level access control

<Note> This is feature is only available if you are on the **Enterprise** tier or above. See [Astro Plans and Pricing](https://www.astronomer.io/pricing/).</Note>

<Warning>
  **Dag-level access control requires Deployment-based forward auth URLs**

  If you use **Dag-level access control**, forward authentication must use the **Deployment-based endpoints**, not the older org-based endpoints.

  When you click **Navigate to Airflow** in the Astro UI, the correct Deployment-based URL appears in your browser address bar.

  Deployment-based URLs follow this format:

  `<deployment-id>.<last-two-characters-of-deployment-id>...`

  You only need to reference or configure these endpoints if you are setting up custom ingress, reverse proxies, or other advanced integrations.

  Dag-level access control permissions are enforced at the **Deployment level**, and using the older org-based URLs can result in incorrect permission enforcement or authentication failures. Note that you may still be feature-flagged to use the older URI format. Contact your account team to enable the new Deployment-based forward auth URLs to use Dag-level access control.
</Warning>

<Info>
  **Astro Runtime 3.1-12+**

  Dag-level access control requires Astro Runtime 3.1-12 or later. Deployments running earlier Runtime versions don't support Dag roles.
</Info>

Astro supports Dag-level role-based access control (RBAC), which adds a fourth tier to the Astro access control hierarchy: Organization > Workspace > Deployment > Dag. Dag roles grant per-Dag permissions to users, Teams, and API tokens within a specific Deployment, so you can enforce least-privilege security and enable multiple teams to collaborate in a single Deployment without exposing Dags across team boundaries.

When you assign a Dag role, you bind it to Dags using either **Dag tags** or **DAG IDs**:

* **Dag tags (recommended)**: Bind roles to one or more [Dag tags](https://airflow.apache.org/docs/apache-airflow/stable/howto/add-dag-tags.html). Any Dag with a matching tag is automatically included in the role binding. This is the recommended approach because new Dags that share the same tag are automatically covered without needing to update role assignments.
* **DAG IDs**: Bind roles to specific Dag IDs. Dag IDs are unique per Deployment. Use this approach when you need to grant access to a specific Dag that doesn't share tags with other Dags.

<Tip>
  Use Dag tags for your role bindings whenever possible. Tag-based bindings scale automatically as you add new Dags, so you won't need to update role assignments every time a new Dag is deployed. For example, tagging all Dags owned by a team with `team:analytics` lets you assign a single Dag role that covers all current and future Dags for that team.
</Tip>

## Prerequisites

* An Astro Deployment running Astro Runtime 3.1-12 or later.
* The user being assigned a Dag role must be an Organization Member. If the user doesn't already have a Workspace role, Astro automatically grants them the Workspace Accessor role when you assign them a Dag role. See [Workspace Accessor](/docs/astro/user-permissions#workspace-roles).
* Organization Owner permissions to create custom Dag roles.
* Workspace Owner or Deployment Admin permissions to assign Dag roles to users, Teams, and API tokens.

## Default Dag roles

Astro provides two default Dag roles that you can assign to users, Teams, and API tokens:

| Role           | Description                                                        |
| -------------- | ------------------------------------------------------------------ |
| **Dag Viewer** | Read-only access to a specific Dag and its resources.              |
| **Dag Author** | Read, edit, and delete access to a specific Dag and its resources. |

To create roles with more granular permissions, see [Create a custom Dag role](#create-a-custom-dag-role).

<Tip>
  **A new Astro UI is here**

  Astronomer 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.
</Tip>

## Assign Dag roles to users

<Tip>You can also manage Dag roles from a Dag-centric view. See [View and manage Dag access from a Dag](#view-and-manage-dag-access-from-a-dag).</Tip>

<Tabs>
  <Tab title="New Astro UI" language="astro-next-ui">
    1. In the Astro UI, click **Settings**.
    2. Under **Access Management**, click **Users**, then click the user you want to manage.
    3. Click the **DAGs** tab.
    4. Click **+ Add DAG**.
    5. In the **Add User to DAG** slide-out, select a **Deployment**.
    6. Under **Target DAG by**, select **DAG Tag** or **DAG ID**. Astronomer recommends using Dag tags so that the role automatically applies to any new Dags with the same tag.
    7. Select the Dag tag or Dag ID you want to bind the role to.
    8. Select a **DAG Role** and click **Add to DAG**.
  </Tab>

  <Tab title="Legacy UI" language="legacy-ui">
    1. In the Astro UI, click **Organization Settings** > **Access Management**.
    2. Click **Users**, then click the user you want to manage.
    3. Click the **DAGs** tab.
    4. Click **+ Dag**.
    5. In the **Add User to DAG** slide-out, select a **Deployment**.
    6. Under **Target DAG by**, select **DAG Tag** or **DAG ID**. Astronomer recommends using Dag tags so that the role automatically applies to any new Dags with the same tag.
    7. Select the Dag tag or Dag ID you want to bind the role to.
    8. Select a **DAG Role** and click **Add to DAG**.
  </Tab>
</Tabs>

## Assign Dag roles to Teams

You can assign Dag roles to Teams so that all Team members share the same Dag-level permissions.

<Tip>You can also manage Dag roles from a Dag-centric view. See [View and manage Dag access from a Dag](#view-and-manage-dag-access-from-a-dag).</Tip>

<Tabs>
  <Tab title="New Astro UI" language="astro-next-ui">
    1. In the Astro UI, click **Settings**.
    2. Under **Access Management**, click **Teams**, then click the Team you want to manage.
    3. Click the **DAGs** tab, then click **+ Add DAG**.
    4. In the slide-out, select a **Deployment**.
    5. Under **Target DAG by**, select **DAG Tag** or **DAG ID**. Astronomer recommends using Dag tags so that the role automatically applies to any new Dags with the same tag.
    6. Select the Dag tag or Dag ID you want to bind the role to.
    7. Select a **DAG Role** and click **Add to DAG**.
  </Tab>

  <Tab title="Legacy UI" language="legacy-ui">
    1. In the Astro UI, click **Organization Settings** > **Access Management**.
    2. Click **Teams**, then click the Team you want to manage.
    3. Click the **DAGs** tab, then click **+ Dag**.
    4. In the slide-out, select a **Deployment**.
    5. Under **Target DAG by**, select **DAG Tag** or **DAG ID**. Astronomer recommends using Dag tags so that the role automatically applies to any new Dags with the same tag.
    6. Select the Dag tag or Dag ID you want to bind the role to.
    7. Select a **DAG Role** and click **Add to DAG**.
  </Tab>
</Tabs>

## Assign Dag roles to API tokens

You can assign Dag roles to Organization, Workspace, and Deployment API tokens to give them fine-grained access to specific Dags within a Deployment. Direct Access tokens can't be assigned Dag roles.

* **Organization API tokens**: Assign Dag roles from **Organization Settings** > **Access Management** > **API Tokens**. Click the token, then use the **DAGs** tab. See the following steps.
* **Workspace API tokens**: Assign Dag roles from the token's access management page. See [Manage Workspace API token access](/docs/astro/workspace-api-tokens#manage-workspace-api-token-access).
* **Deployment API tokens**: Assign Dag roles from the token's access management page. See [Manage Deployment API token access](/docs/astro/deployment-api-tokens#manage-deployment-api-token-access).

To assign a Dag role to an Organization API token:

<Tabs>
  <Tab title="New Astro UI" language="astro-next-ui">
    1. In the Astro UI, click **Settings**.
    2. Under **Access Management**, click **API Tokens**, then click the Organization API token you want to manage.
    3. Click the **DAGs** tab, then click **+ Add DAG**.
    4. In the slide-out, select a **Deployment**.
    5. Under **Target DAG by**, select **DAG Tag** or **DAG ID**. Astronomer recommends using Dag tags so that the role automatically applies to any new Dags with the same tag.
    6. Select the Dag tag or Dag ID you want to bind the role to.
    7. Select a **DAG Role** and click **Add to DAG**.
  </Tab>

  <Tab title="Legacy UI" language="legacy-ui">
    1. In the Astro UI, click **Organization Settings** > **Access Management**.
    2. Click **API Tokens**, then click the Organization API token you want to manage.
    3. Click the **DAGs** tab, then click **+ Dag**.
    4. In the slide-out, select a **Deployment**.
    5. Under **Target DAG by**, select **DAG Tag** or **DAG ID**. Astronomer recommends using Dag tags so that the role automatically applies to any new Dags with the same tag.
    6. Select the Dag tag or Dag ID you want to bind the role to.
    7. Select a **DAG Role** and click **Add to DAG**.
  </Tab>
</Tabs>

<Tip>You can also manage Dag roles from a Dag-centric view. See [View and manage Dag access from a Dag](#view-and-manage-dag-access-from-a-dag).</Tip>

## View and edit a user's Dag access

Organization Owners can view and manage all of a user's Dag role assignments from a centralized page.

<Tabs>
  <Tab title="New Astro UI" language="astro-next-ui">
    1. In the Astro UI, click **Settings**.

    2. Under **Access Management**, click **Users**, then click the user whose Dag access you want to view.

    3. Click the **DAGs** tab.
  </Tab>

  <Tab title="Legacy UI" language="legacy-ui">
    1. In the Astro UI, click **Organization Settings** > **Access Management**.

    2. Click **Users**, then click the user whose Dag access you want to view.

    3. Click the **DAGs** tab.
  </Tab>
</Tabs>

The **DAGs** tab lists explicit Dag role assignments across all Deployments. Users may also have additional access through their Deployment, Workspace, or Organization role, or through a Team membership. The table shows the following columns:

* **DAG ID**: The ID of the Dag the role is bound to.
* **DAG Tag**: The Dag tag the role is bound to.
* **Deployment**: The Deployment the binding belongs to.
* **DAG Role**: The Dag role assigned to the user.

To edit a user's Dag role:

1. Open the **More actions** menu (⋯) next to the Dag entry you want to update and select **Edit role**.

2. In the **Edit Dag Access** slide-out, select a new Dag role. The **DAG ID** and **Deployment** fields are read-only.

3. Click **Save changes**.

To remove a user's access to a Dag, open the **More actions** menu (⋯) and select **Remove**.

## View and manage Dag access from a Dag

Organization Owners can view and manage all role assignments for a specific Dag from the Dag's **Access Management** page. This provides a Dag-centric view of access, showing all users, Teams, and API tokens that have roles on a particular Dag.

<Tabs>
  <Tab title="New Astro UI" language="astro-next-ui">
    1. In the Astro UI, click **DAGs**, then click the Dag you want to manage.

    2. Click the **Access** tab, then toggle between **Users**, **Teams**, and **API Tokens**.
  </Tab>

  <Tab title="Legacy UI" language="legacy-ui">
    1. In the Astro UI, open the **DAGs** page for your Deployment.

    2. Open the **More actions** menu (⋯) for the Dag you want to manage and click **Access Management**.
  </Tab>
</Tabs>

The **Access Management** page shows three tabs:

* **Users**: All users with Dag roles on this Dag.
* **Teams**: All Teams with Dag roles on this Dag.
* **API Tokens**: All API tokens with Dag roles on this Dag.

Roles assigned by **DAG ID** can be added, edited, or removed from this page. Roles assigned by **DAG Tag** are view-only because they are managed through the tag-based binding. To edit a tag-based role, go to **Organization Settings** > **Access Management** and manage the role from the entity's **DAGs** tab.

### Add a Dag role from the Dag Access Management page

1. Click the tab for the entity type you want to add (**Users**, **Teams**, or **API Tokens**).

2. Click **+ User**, **+ Team**, or **+ API Token**, depending on the selected tab.

3. In the slide-out:

   * For **Users** and **Teams**: Select the entity and a **DAG Role**, then click **Add**.
   * For **API Tokens**: Select a **Scope** (Deployment, Workspace, or Organization) to filter the available tokens. Select an **API Token** and a **DAG Role**, then click **Add**.

<Note>Direct Access tokens appear in the token dropdown but aren't selectable.</Note>

### Edit or remove a Dag role from the Dag Access Management page

1. Open the **More actions** menu (⋯) next to the entity you want to update.

2. Click **Edit role** to change the Dag role, or click **Remove from Dag** to remove the entity's access to the Dag.

<Tip>Click an entity's name on the **Access Management** page to navigate to its details page, where you can view and manage all of its role assignments.</Tip>

## Create a custom Dag role

You can create custom Dag roles with granular permissions at the Organization level. After you create a custom Dag role, you can assign it to users, Teams, and API tokens for any Dag in any Deployment in the Organization.

<Tabs>
  <Tab title="New Astro UI" language="astro-next-ui">
    1. In the Astro UI, click **Settings**.

    2. Under **Access Management**, click **Roles & Permissions**.

    3. Click **Custom**, then click **+ New Custom Role**.

    4. In the slide-out that appears, set the **Scope** dropdown to **Dag**.

    5. Enter a **Name** and **Description** for the role.

    6. (Optional) Use the **Copy from an existing role** dropdown to load the permissions of a default Dag role or an existing custom role as a starting point.

    7. In the **Permissions** table, check the boxes for the permissions you want the role to have. See [Custom role permissions reference](/docs/astro/deployment-role-reference#dag-scope-permissions) for a complete list of available permissions.

    8. Click **Create Role**.
  </Tab>

  <Tab title="Legacy UI" language="legacy-ui">
    1. In the Astro UI, click **Organization Settings**.

    2. Go to **Access Management**, then click **Roles**.

    3. Click **Custom**, then click **+ Add Role**.

    4. In the slide-out that appears, set the **Scope** dropdown to **Dag**.

    5. Enter a **Name** and **Description** for the role.

    6. (Optional) Use the **Copy from an existing role** dropdown to load the permissions of a default Dag role or an existing custom role as a starting point.

    7. In the **Permissions** table, check the boxes for the permissions you want the role to have. See [Custom role permissions reference](/docs/astro/deployment-role-reference#dag-scope-permissions) for a complete list of available permissions.

    8. Click **Create Role**.
  </Tab>
</Tabs>

Your custom Dag role is now available to assign to users, Teams, and API tokens at the Dag level in any Deployment.

### Custom Dag roles vs. custom Deployment roles

Custom Deployment roles and custom Dag roles both use the custom role creation flow in **Organization Settings** > **Access Management** > **Roles**, but they differ in scope:

* **Custom Deployment roles** grant permissions across all Dags and resources in a Deployment. See [Create and assign custom Deployment roles](/docs/astro/customize-deployment-roles).
* **Custom Dag roles** grant permissions to specific Dags within a Deployment, bound by Dag tag or Dag ID.

A user can have both a Deployment role and one or more Dag roles. Permissions are additive, meaning a user with multiple roles has the combined permissions of all their roles.

## Permission dependencies for custom Dag roles

Most Airflow operations require a specific combination of permissions to work. Assigning a resource-specific permission without the required base permission results in access being denied, even when the user appears to have the relevant permission.

Two base permission patterns apply across all resources:

* **Read operations** require `dag.airflow.dag.get` alongside the specific resource read permission. For example, to view Dag runs, a role needs both `dag.airflow.dag.get` and `dag.airflow.dagRun.get`.
* **Write operations** (create, update, delete) require `dag.airflow.dag.update` — not `dag.airflow.dag.get` — alongside the specific resource write permission. For example, to trigger a Dag run, a role needs `dag.airflow.dag.update` and `dag.airflow.dagRun.create`.

Some nested resources also require permissions for all parent resources. For example, viewing task logs requires `dag.airflow.dag.get`, `dag.airflow.dagRun.get`, `dag.airflow.taskInstance.get`, and `dag.airflow.taskLog.get`.

### Common permission sets

The following examples show minimum permission sets for common role types. These are verified against Airflow API behavior but cover a subset of operations. Not all Airflow endpoints are represented here.

<AccordionGroup>
  <Accordion title="Read-only access">
    View Dags, Dag runs, and task execution details without making changes.

    ```text wrap theme={null}
    dag.airflow.dag.get
    dag.airflow.dagRun.get
    dag.airflow.taskInstance.get
    dag.airflow.taskLog.get
    ```
  </Accordion>

  <Accordion title="Dag operator">
    Trigger, update, and delete Dag runs.

    ```text wrap theme={null}
    dag.airflow.dag.get
    dag.airflow.dag.update
    dag.airflow.dagRun.get
    dag.airflow.dagRun.create
    dag.airflow.dagRun.update
    dag.airflow.dagRun.delete
    ```
  </Accordion>

  <Accordion title="Task manager">
    View and manage individual task instances.

    ```text wrap theme={null}
    dag.airflow.dag.get
    dag.airflow.dag.update
    dag.airflow.dagRun.get
    dag.airflow.taskInstance.get
    dag.airflow.taskInstance.update
    dag.airflow.taskInstance.delete
    ```
  </Accordion>

  <Accordion title="Dag administrator">
    Full control over a Dag, including deletion.

    ```text wrap theme={null}
    dag.airflow.dag.get
    dag.airflow.dag.update
    dag.airflow.dag.delete
    dag.airflow.dagRun.get
    dag.airflow.dagRun.create
    dag.airflow.dagRun.update
    dag.airflow.dagRun.delete
    ```
  </Accordion>
</AccordionGroup>

<Warning>
  The [Airflow access control documentation](https://airflow.apache.org/docs/apache-airflow/2.8.3/security/access-control.html) covers a broader set of permissions but isn't consistently maintained and may not reflect actual enforcement behavior. Use it as a general reference and verify requirements in your Deployment.
</Warning>

## See also

* [User permissions reference](/docs/astro/user-permissions)
* [Create and assign custom Deployment roles](/docs/astro/customize-deployment-roles)
* [Custom role permissions reference](/docs/astro/deployment-role-reference)
* [Configure Teams on Astro](/docs/astro/manage-teams)
* [Create and manage Organization API tokens](/docs/astro/organization-api-tokens)