Backfill permissions

A backfill reruns a Dag for a historical date range. On Astro Private Cloud (APC), the Houston API issues a JWT for each user when they access the Airflow UI or API. The JWT carries the user’s mapped Airflow role and the corresponding permissions. Airflow enforces backfill access against those permissions.

This page describes the APC-specific role mapping and how to grant, revoke, and audit backfill access. For general Airflow concepts, CLI flags, and UI behavior, see the related Astronomer Learn guides:

• Rerun Airflow Dags and tasks (Airflow 2.x)
• Rerun Airflow Dags and tasks (Airflow 3.x)

For general user role assignment outside the backfill scope, see Manage users on Astro Private Cloud and the User roles and permissions reference.

Permission model

Houston deployment role to Airflow role

When a user opens the Airflow UI or API for a Deployment, Houston maps the user’s deployment-level role to an Airflow role and encodes the matching permission set in the JWT.

Backfill actions

The backfill resource supports four actions.

How permission changes propagate

Houston issues a JWT when the user accesses the Airflow UI. The JWT lifetime is controlled by the jwt.authDuration Houston config and defaults to 24 hours. A role change takes effect when Houston issues a new JWT, typically on the user’s next sign-in or token refresh. Until then, the existing JWT continues to grant the previous permissions, so a role change can take up to 24 hours to reach an active session. To force the change immediately, have the user sign out and sign back in.

Prerequisites

• The user has DEPLOYMENT_EDITOR or DEPLOYMENT_ADMIN on the target Deployment, or an inherited role from the Workspace or system level.
• The Dag exists and is unpaused.
• The target date range is valid for the Dag’s schedule.

Trigger a backfill

The trigger mechanism depends on the Airflow version running in your Deployment.

$
airflow dags backfill \
>
  --start-date 2026-01-01 \
>
  --end-date 2026-01-31 \
>
  --reset-dagruns \
>
  <dag-id>

Manage backfill access

Backfill access uses the standard APC role-assignment flow. For the full reference, see Manage users on Astro Private Cloud. The examples in this section show the calls scoped to backfill use cases.

Grant or change a role

1
mutation {
2
  deploymentAddUserRole(
3
    deploymentId: "<deployment-id>"
4
    email: "<user-email>"
5
    role: DEPLOYMENT_EDITOR
6
  ) {
7
    id
8
  }
9
}

Restrict to read-only access

Use the same Houston API or Astro CLI commands with role: DEPLOYMENT_VIEWER (or --role=DEPLOYMENT_VIEWER). The user can view backfill status and history but can’t create, modify, or cancel backfills.

Revoke access

To remove a user from the Deployment entirely, use the Houston deploymentRemoveUserRole mutation or astro deployment user remove.

1
mutation {
2
  deploymentRemoveUserRole(
3
    deploymentId: "<deployment-id>"
4
    email: "<user-email>"
5
  ) {
6
    id
7
  }
8
}

After the role binding is removed, the user retains their previous backfill capabilities until their JWT expires. See How permission changes propagate.

Monitor backfills

Use the Airflow UI

Backfill runs appear in the Dag’s run list with a backfill run-type label, alongside scheduled and manually triggered runs.

Query the metadata database

Backfill Dag runs are stored in the dag_run table with run_type = 'backfill'.

1
SELECT dag_id, run_type, state, start_date, end_date
2
FROM dag_run
3
WHERE run_type = 'backfill'
4
ORDER BY start_date DESC;

Troubleshoot

Access denied when creating a backfill

The user has DEPLOYMENT_VIEWER, which only grants backfill.read. Promote them with deploymentUpdateUserRole:

1
mutation {
2
  deploymentUpdateUserRole(
3
    deploymentId: "<deployment-id>"
4
    email: "<user-email>"
5
    role: DEPLOYMENT_EDITOR
6
  ) {
7
    id
8
  }
9
}

Backfills aren’t visible to a user

The user has no role on the Deployment. Add them with at least DEPLOYMENT_VIEWER. If the user holds WORKSPACE_VIEWER and still can’t see the Deployment, confirm the Deployment is in the same Workspace.

A role change hasn’t taken effect

The user is still presenting their existing JWT, which keeps the previous permissions until it expires. The default JWT lifetime is 24 hours. Have the user sign out and sign back in to force Houston to issue a fresh token. If they authenticate through SSO, ensure the IdP session is also refreshed.

Best practices

• Assign DEPLOYMENT_EDITOR to operators who run backfills regularly. Reserve DEPLOYMENT_ADMIN for users who also manage Deployment configuration.
• Assign DEPLOYMENT_VIEWER to stakeholders who only need to monitor Dag runs.
• Use a Deployment service account with DEPLOYMENT_EDITOR for automated backfills triggered from CI or scheduled jobs, rather than a personal user token.
• Audit backfill activity by querying dag_run.run_type = 'backfill' or by reviewing the Dag’s run list.
• Test large historical backfills in a non-production Deployment first.
• Set worker concurrency and Dag-level max_active_runs to limit the load a backfill places on the Deployment.