API Authentication and JWT
Purpose and Scope
Airflow exposes API surfaces for people, automation, and runtime components, so API security has two related jobs: authenticate the caller and authorize the requested action. Authentication answers who is calling, while authorization answers whether that identity may perform an operation. In the FAB provider path shown here, API and UI-adjacent FastAPI routes can use dependency injection to retrieve the current user and then delegate permission decisions to the active auth manager. JWT token authentication, described in the official security documentation, fits into the authentication side by carrying signed identity and scope information between Airflow components or API clients.
The official JWT documentation separates REST API authentication from Execution API authentication. That distinction matters operationally. REST API tokens are user- or client-facing credentials for the stable API and include concepts such as acquisition, validation, refresh, revocation, token structure, and default timings. Execution API tokens are runtime-oriented credentials delivered to workers for task execution interactions; they emphasize generated scopes, worker delivery, validation, refresh, and current limitations around revocation. Treat both as signed bearer-token flows, but do not assume their lifecycle controls are identical.
Sources: providers/fab/src/airflow/providers/fab/auth_manager/api_fastapi/security.py, providers/fab/src/airflow/providers/fab/auth_manager/security_manager/constants.py
Relevant Source Files
providers/fab/src/airflow/providers/fab/auth_manager/api_fastapi/security.pycontains the FastAPI dependency factory used by FAB custom views to enforce authorization through the active Airflow auth manager.providers/fab/src/airflow/providers/fab/auth_manager/security_manager/constants.pydefines the built-in FAB role names that deployments commonly see when mapping authenticated users to Airflow permissions.providers/fab/src/airflow/providers/fab/auth_manager/security_manager/__init__.pymarks the FAB security-manager package boundary used by the provider implementation.providers/fab/src/airflow/providers/fab/auth_manager/security_manager/override.pybelongs to the same FAB security-manager implementation area and is part of the requested API authentication source set.docs/images/documentation_architecture.pydocuments how Airflow documentation is produced and published, which explains why the JWT authentication guide is maintained as part of the project documentation surface rather than only as code comments.
Sources: docs/images/documentation_architecture.py, providers/fab/src/airflow/providers/fab/auth_manager/api_fastapi/security.py, providers/fab/src/airflow/providers/fab/auth_manager/security_manager/init.py, providers/fab/src/airflow/providers/fab/auth_manager/security_manager/constants.py, providers/fab/src/airflow/providers/fab/auth_manager/security_manager/override.py
System-to-Code Mapping
The source-level authorization hook for FAB custom views is intentionally small. requires_fab_custom_view(method: str, resource_name: str) returns an inner FastAPI dependency named _check. FastAPI resolves the current user through Depends(get_user), and the dependency then calls get_auth_manager().is_authorized_custom_view(method=method, resource_name=resource_name, user=user). If the active auth manager denies access, the dependency raises HTTPException with HTTP status 403 Forbidden and the response detail Forbidden. This is the concrete point where a route-level method and resource name become an auth-manager authorization request.
This design keeps token parsing and route authorization separate. A JWT or another authentication mechanism must first establish a user object that get_user can provide to dependencies. After that, provider code does not need to know whether the identity came from a browser session, REST API token, or another supported authenticator. The route dependency only depends on the normalized user and the active auth manager. That separation is important for Airflow installations because auth managers are a public extension category in the Airflow 3 interface, while individual deployments may choose different identity providers and authentication policies.
FAB role names are represented as a small constant set: Admin, Viewer, User, Op, and Public. These names are not a complete permission model by themselves; they are stable labels used by the FAB security manager area when representing familiar built-in roles. In practice, administrators should read them as role identities that may be bound to permissions and users by the active auth manager and security-manager configuration. JWT authentication establishes the principal and claims; role and permission evaluation decides whether the principal can access a custom view, REST operation, or other protected resource.
Sources: providers/fab/src/airflow/providers/fab/auth_manager/api_fastapi/security.py, providers/fab/src/airflow/providers/fab/auth_manager/security_manager/constants.py
REST API JWT Flow
For the stable REST API, the official documentation frames JWT authentication as a lifecycle: token acquisition, token structure, token validation, token revocation, token refresh, and default timings. A client first obtains a token through the configured authentication mechanism. It then presents that token with API requests as a bearer credential. Airflow validates that the token is signed correctly, is still within its validity window, and represents an acceptable caller. After validation, request handling can resolve the user and run authorization checks such as the FAB custom-view dependency described above.
Revocation and refresh are the REST API lifecycle features to plan most carefully. Refresh allows clients to continue working without repeatedly performing full authentication, while revocation gives operators a way to invalidate tokens before their natural expiry. Default timings influence both security and user experience: short-lived tokens reduce exposure if leaked, but they require reliable refresh behavior; longer-lived tokens reduce friction but increase the importance of secret handling and revocation. When integrating automation, record which identity obtains the token, where it is stored, and which Airflow permissions it needs.
At the route level, a successful REST API authentication flow should result in a user context that can be consumed by dependencies. The FAB provider example shows the downstream shape of that contract: the route supplies a method and resource name, the dependency obtains the user, and the auth manager decides whether the action is allowed. If a JWT is valid but the user lacks permission, the correct outcome is not an authentication challenge; it is an authorization failure, represented here by 403 Forbidden. That distinction helps clients distinguish expired or invalid credentials from insufficient privileges.
Sources: providers/fab/src/airflow/providers/fab/auth_manager/api_fastapi/security.py
Execution API JWT Flow
Execution API authentication is aimed at Airflow runtime communication rather than general user-driven API access. The official documentation describes token generation, token structure, token scopes, token delivery to workers, validation, refresh, and the absence of token revocation for that flow. The key term is scope: a scope narrows what a token is intended to authorize. Instead of handing workers a broad user API token, Airflow can use a runtime token whose claims are shaped for task execution interactions and worker communication.
This difference changes the operational threat model. REST API tokens are usually managed around users, service accounts, and external clients. Execution API tokens are part of task runtime and workload isolation. They must be delivered to workers safely, refreshed according to their runtime rules, and validated by the receiving API. Because the official documentation calls out no token revocation for the Execution API flow, deployments should rely on short lifetimes, controlled delivery paths, and workload isolation rather than assuming the same revocation behavior available for REST API tokens.
The FAB authorization dependency remains useful as a mental model even when reading about execution tokens: authentication produces a trusted principal or runtime identity, then authorization evaluates the requested action. Execution API authorization may use different scopes and runtime checks from a custom FAB view, but the separation of concerns is the same. Do not design integrations that treat possession of a JWT as unlimited access. A token is evidence presented to Airflow; the active API layer and auth manager still determine what that evidence allows.
Sources: providers/fab/src/airflow/providers/fab/auth_manager/api_fastapi/security.py
API Components Reference
| Component | Public shape shown in source | Behavior |
|---|---|---|
| FAB custom-view dependency | requires_fab_custom_view(method: str, resource_name: str) | Returns a FastAPI dependency that checks whether the current user is authorized for a named custom view action. |
| User resolution | Depends(get_user) | Lets FastAPI inject the authenticated Airflow user before authorization runs. |
| Auth-manager delegation | get_auth_manager().is_authorized_custom_view(...) | Delegates the permission decision to the configured auth manager using method, resource name, and user. |
| Denial response | HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Forbidden") | Converts an authorization denial into a standard HTTP 403 response. |
| Built-in role labels | EXISTING_ROLES = {"Admin", "Viewer", "User", "Op", "Public"} | Provides the FAB security-manager role-name set visible in the provider implementation. |
When adding or reviewing a protected FAB custom view, choose the method and resource_name values deliberately. They are the identifiers the auth manager receives, so they should correspond to meaningful operations rather than incidental route names. The dependency should be attached where FastAPI will execute it before the protected handler does sensitive work. If a caller reports a 403, inspect the resolved user and role mapping before debugging token cryptography; a valid JWT can still map to a user that lacks the required custom-view permission.
Sources: providers/fab/src/airflow/providers/fab/auth_manager/api_fastapi/security.py, providers/fab/src/airflow/providers/fab/auth_manager/security_manager/constants.py
Documentation and Operational Signals
The repository also includes a generated documentation architecture diagram showing how Airflow documentation moves from GitHub repositories to the live documentation site. The diagram code models release managers, committers, the apache-airflow and apache-airflow-site repositories, S3-backed live docs, CloudFront caching, and the public https://airflow.apache.org webserver. For API authentication, this matters because JWT behavior is partly an operator-facing contract: configuration defaults, lifecycle descriptions, and security limitations must be read from the versioned documentation that matches the deployed Airflow release.
Use the documentation version selector when validating JWT behavior for a running cluster. Airflow’s JWT defaults, public API expectations, and auth-manager contracts can change across releases, and the documentation publishing workflow exists to make package documentation available alongside the project site. For implementation review, start with the auth-manager dependency code and role constants on this page. For deployment work, pair that code reading with the official JWT Token Authentication guide, the Public API security page, and the auth-manager documentation for the provider selected in your environment.
Sources: docs/images/documentation_architecture.py, providers/fab/src/airflow/providers/fab/auth_manager/api_fastapi/security.py
Next Steps
For a new API integration, first decide whether it needs REST API access or is participating in the task execution runtime. Next, configure token acquisition and storage according to the matching JWT flow, then grant the smallest Airflow role and permission set required. Finally, test both failure modes: an invalid or expired token should fail authentication, while a valid token without the required permission should produce an authorization denial such as the FAB 403 Forbidden path. Related pages to read next are security-model, auth-managers, rest-api-and-openapi-clients, and secrets-backends-and-masking.