Skip to main content

Documentation Index

Fetch the complete documentation index at: https://astronomer-preview.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

This is feature is only available if you are on theEnterprisetier or above. SeeAstro Plans and Pricing.
Private PreviewThis feature is inPrivate Preview. Reach out to your account team to enable this feature.
Dag-level access control requires Deployment-based forward auth URLsIf 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. Reach out to your account team to enable the new Deployment-based forward auth URLs to use Dag-level access control.
Astro Runtime 3.1-12+Dag-level access control requires Astro Runtime 3.1-12 or later. Deployments running earlier Runtime versions do not support Dag roles.
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. 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.
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.

​
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 does not already have a Workspace role, Astro automatically grants them the Workspace Accessor role when you assign them a Dag role. See Workspace Accessor.
  • 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:
RoleDescription
Dag ViewerRead-only access to a specific Dag and its resources.
Dag AuthorRead, edit, and delete access to a specific Dag and its resources.
To create roles with more granular permissions, see Create a custom Dag role.

​
Assign Dag roles to users

You can also manage Dag roles from a Dag-centric view. SeeView and manage Dag access from a Dag.
  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.

​
Assign Dag roles to Teams

You can assign Dag roles to Teams so that all Team members share the same Dag-level permissions.
You can also manage Dag roles from a Dag-centric view. SeeView and manage Dag access from a Dag.
  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.

​
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 cannot 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.
  • Deployment API tokens: Assign Dag roles from the token’s access management page. See Manage Deployment API token access.
To assign a Dag role to an Organization API token:
  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.
You can also manage Dag roles from a Dag-centric view. SeeView and manage Dag access from a Dag.

​
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.
  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.
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.
  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.
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.
Direct Access tokens appear in the token dropdown but are not selectable.

​
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.
Click an entity’s name on theAccess Managementpage to navigate to its details page, where you can view and manage all of its role assignments.

​
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.
  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 for a complete list of available permissions.
  8. Click Create Role.
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.
  • 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.
View Dags, Dag runs, and task execution details without making changes.
dag.airflow.dag.get
dag.airflow.dagRun.get
dag.airflow.taskInstance.get
dag.airflow.taskLog.get
Trigger, update, and delete Dag runs.
dag.airflow.dag.get
dag.airflow.dag.update
dag.airflow.dagRun.get
dag.airflow.dagRun.create
dag.airflow.dagRun.update
dag.airflow.dagRun.delete
View and manage individual task instances.
dag.airflow.dag.get
dag.airflow.dag.update
dag.airflow.dagRun.get
dag.airflow.taskInstance.get
dag.airflow.taskInstance.update
dag.airflow.taskInstance.delete
Full control over a Dag, including deletion.
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
The Airflow access control documentation covers a broader set of permissions but is not consistently maintained and may not reflect actual enforcement behavior. Use it as a general reference and verify requirements in your Deployment.

​
See also