Public API

Airflow public API authentication

The Airflow public API uses JWT (JSON Web Token) for authenticating API requests. Each request made to the Airflow API must include a valid JWT token in the Authorization header to verify the identity and permissions of the client.

Generate a JWT token

To interact with the Airflow API, clients must first authenticate and obtain a JWT token. The token can be generated by making a POST request to the /auth/token endpoint, passing the necessary credentials (e.g., username and password). The /auth/token endpoint is provided by the auth manager, therefore, please read the documentation of the auth manager configured in your environment for more details. The request format and supported content types are also defined by the configured auth manager.

The list of supported auth managers is available in Auth managers list.

Example

Request

The following example uses a JSON request body. Check the configured auth manager’s documentation for its required request format and content type.

ENDPOINT_URL="http://localhost:8080"
curl -X POST ${ENDPOINT_URL}/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your-username",
    "password": "your-password"
  }'

Response

The successful response status code and response fields are defined by the configured auth manager. Auth managers return the JWT in the access_token field. For example:

{
  "access_token": "<JWT-TOKEN>"
}

For the status code and any additional response fields, see the documentation for the auth manager configured in your environment.

Use the JWT token to call Airflow public API

ENDPOINT_URL="http://localhost:8080"
curl -X GET ${ENDPOINT_URL}/api/v2/dags \
  -H "Authorization: Bearer <JWT-TOKEN>"

Enabling CORS

Cross-origin resource sharing (CORS) is a browser security feature that restricts HTTP requests that are initiated from scripts running in the browser.

Access-Control-Allow-Headers, Access-Control-Allow-Methods, and Access-Control-Allow-Origin headers can be added by setting values for access_control_allow_headers, access_control_allow_methods, and access_control_allow_origins options in the [api] section of the airflow.cfg file.

[api]
access_control_allow_headers = origin, content-type, accept
access_control_allow_methods = POST, GET, OPTIONS, DELETE
access_control_allow_origins = https://exampleclientapp1.com https://exampleclientapp2.com

Airflow’s API always responds with Access-Control-Allow-Credentials: true so the UI and clients can send cookies and Authorization headers across origins. Because of that, access_control_allow_origins must list the exact origins that need access — the wildcard * is rejected at startup. The CORS spec forbids combining Access-Control-Allow-Origin: * with credentialed responses, and browsers refuse any response that does so, so a wildcard origin would simply break every cross-origin request.

Page size limit

To protect against requests that may lead to application instability, the stable API has a limit of items in response. The default is 100 items, but you can change it using maximum_page_limit option in [api] section in the airflow.cfg file.

Request Payload Considerations

When using REST APIs that accept data payloads (such as the Variables API), be mindful of the payload size. Large payloads (out of ordinary size, like a million bytes) can impact the performance of the Airflow webserver. It’s recommended to implement appropriate size limits at the proxy layer for your deployment.