How to migrate Airflow REST API v1 clients to API v2
If your scripts, CI jobs or integrations call /api/v1, they will stop working when you move to Airflow 3, because Airflow 3 removes the REST API v1 and serves its replacement at /api/v2. The migration means updating each client to the v2 paths, changing how it authenticates, and checking every place it reads or writes Airflow data. Start with an inventory of clients, because v1 calls often hide in cron jobs, deployment pipelines and dashboards that nobody has touched in a long time.
The removal follows from the same security direction as the other Airflow 3 changes. Task code can no longer reach the metadata database directly and must use the REST API or Task SDK instead, so the API becomes the supported control surface for external automation. Upgrade in the order the upgrade guide sets out: be on Airflow 2.7 or later before upgrading, and move to the latest 2.x line first so you can test client changes against a release that still serves v1. Confirm the exact minimum and latest versions against the Upgrading to Airflow 3 guide before you schedule the move.
Plan the timeline around support status. Airflow 2 reached end of life on April 22, 2026, so Airflow 2 installations no longer receive fixes, and a client migration that waits for a later cutover leaves you running an unpatched control plane in the meantime. Confirm with your platform owners which Airflow version each environment runs, which clients call v1 in each environment, and whether any integration relies on basic authentication. Those three answers determine whether you can migrate clients on 2.x first or must move the platform before the clients.
What changes between /api/v1 and /api/v2
This table compares how Airflow 2 API v1 clients behave against Airflow 3 API v2 and what each change asks your team to do. Read each row as a checklist item for scripts, CI jobs and integrations, and confirm the final behavior against the Airflow release you target.
| Change | Impact | Action needed |
|---|---|---|
| REST API /api/v1 removed in Airflow 3 | Calls to /api/v1 endpoints stop working after the upgrade, so scripts and CI jobs that hard-code the path fail. | Inventory every client that calls /api/v1 and repoint each one to /api/v2 before cutover. |
| Token authentication replaces basic auth | Clients that send username and password on each request need to obtain and send a token instead. | Create a token request step using the auth manager's token endpoint and update each client's credential handling. |
| Token endpoint usually POST /auth/token | Automation has no fixed token call to copy from v1 examples, so it may be written against the wrong route. | Confirm the token endpoint for your auth manager and test it in a staging environment. |
| Auth routes move under the /auth prefix | Hard-coded login or auth URLs in integrations and reverse proxy rules stop matching. | Search configuration and proxy rules for auth paths and update them to the /auth prefix. |
| OAuth callback URLs must be updated | Single sign-on logins can fail after upgrade if the identity provider still points at the old callback. | Register the new callback URLs with your identity provider and test sign-in before cutover. |
| Simple auth manager is the default | Teams that never configured an auth manager may find token behavior and user roles differ from Airflow 2. | Decide whether to keep Simple or set the auth_manager option to FAB or another manager, then test client access. |
| Explicit bearer credential takes precedence (3.3.2) | An invalid bearer token returns 401 or 403 even when a valid browser session cookie is present. | Confirm the Airflow version you run, and make sure clients send only valid tokens and never rely on a cookie. |
| Python client and call signatures | Client version and method signatures may differ from the calls your scripts use. | Confirm the Python client version and its call signatures against the Airflow release your team targets before changing code. |
Which authentication change applies to each client
Engineers and operators who run scripts by hand usually have a working command that sends basic auth to /api/v1. On Airflow 3, that call changes shape: the script first requests a token from the auth manager, then sends that token as a bearer credential to /api/v2. The exact request depends on which auth manager your deployment runs, so confirm the details in the auth manager documentation.
- Token request: Post the user's credentials to the token endpoint, usually
POST /auth/token, and use the returned token on every /api/v2 call. - Storage: Keep tokens out of script files, shell history and shared notes. Use the password manager or secrets tool your team already runs for personal credentials.
- Refresh: Where the auth manager supports it, expired tokens are refreshed through its refresh_user method. Where it does not, the script should request a new token and retry once.
- Browser sessions: The UI keeps its token in an httponly cookie named
_token. Scripts should request their own token and leave the browser cookie alone.
Confirm the token lifetime for your auth manager and whether refresh_user is implemented for it before you retire any basic auth commands.
Unattended CI jobs have no person to type a password, so they need a non-personal identity, a secret store and a token request at the start of each run. A job should fail fast if the token request fails, and it should never print the token into build logs.
- Service identity: Create a dedicated Airflow user for each pipeline or group of related jobs, so audit logs show the job and not an individual.
- Secret storage: Hold credentials in the CI system's secret store with masking enabled, and limit them to the branches or environments that need them.
- Token per run: Request a token when the job starts and discard it when the job ends. Do not share tokens across pipelines.
- One credential per request: From Airflow 3.3.2, an explicit bearer credential takes precedence over the session cookie. An invalid explicit credential fails with 401 or 403 even when a valid cookie is present. Remove stale token variables from wrapper scripts and shared images so each request carries one credential.
Before changing production variables, confirm the service account's role mapping in your auth manager and test the job against a staging Airflow 3 instance.
Monitoring jobs, ticketing hooks, data catalogs and internal portals call the Airflow API with credentials that someone configured long ago. Some of these integrations also use OAuth to sign users in. Those flows break when auth routes move under the /auth prefix, because the callback URL registered with the identity provider may no longer match the one Airflow sends.
- Inventory: List every integration, the credential it uses, whether that credential belongs to a service account or a user login, and the Airflow version it was built for.
- Callback URLs: Update OAuth callback URLs in the identity provider so they point to the /auth paths on Airflow 3. Keep the old URLs registered until cutover is complete.
- Token support: Ask each vendor whether the integration can request a bearer token from the token endpoint or can only send basic auth. If it cannot, ask for a dated plan to support token authentication.
- Credential rotation: Rotate the credentials when an integration moves to token auth, so any basic auth password missed during the change stops working.
Review the upgrade guide for the full list of route changes, then test each integration's sign-in and API calls in staging before cutover.
Teams that wrote code against an Airflow Python client or a generic HTTP library need to confirm which client release targets /api/v2 and how it accepts a token. The client's configuration may still expect basic auth parameters or a v1 base path, so changing the version alone does not guarantee that the calls will work.
- Version check: Identify the client release your code uses and confirm from its documentation that it calls /api/v2 and supports token authentication.
- Configuration keys: Review connection settings, base URLs and environment variables. Old basic auth keys may be ignored or may fail without a clear error, so test each one explicitly.
- Pinning: Pin the client version in your project's lock file and upgrade it together with the Airflow server.
- Error handling: On a 401 or 403 response, request a fresh token once, then fail with a clear message. Avoid retry loops that hide an expired or invalid credential.
Run the client's calls against a staging Airflow 3 instance and compare each response with the v1 behavior your code depended on before the production change.
Why the 3.3.2 credential precedence change can break mixed clients
In Airflow 3.3.2, released September 17, 2026, an explicit bearer credential takes precedence over the session cookie. Before this change, a client that sent both could succeed on the strength of the cookie even when its own token was wrong. Now an invalid explicit credential fails with 401 or 403 even when a valid session cookie is present. Any script, CI job or integration that was quietly relying on the cookie fallback will start failing after the upgrade, and the error will point at the token, not at the browser state that was masking the problem.
The clients most at risk are those that send a bearer token and also carry browser session state. Examples include a shared service account whose requests pass through a tool that keeps a logged-in browser cookie jar, a notebook or internal portal that calls /api/v2 with a hard-coded token while the user is signed in to the UI, and any client that refreshes or rotates tokens but keeps an old value in a config file or secret store. Tokens issued by the /auth/token endpoint expire, so a stale token that once worked will now fail visibly instead of being absorbed by the cookie. Confirm with your own inventory which clients send an Authorization header and which also hold a session.
To test, run each migrated client against a Airflow 3.3.2 staging environment in two conditions: once with only the bearer token, and once from a context that also holds a valid session cookie, such as a browser profile signed in to the UI. Deliberately use an expired or wrong token in both runs. Any call that succeeds in the second condition but fails in the first has been depending on the cookie. Record the status codes, then fix the client to send one correct credential, refresh tokens through the auth manager flow, and remove cookie reuse from automation. The Airflow release notes are the reference for the exact behavior in your patch level.
Inventory every caller before changing any code
Every script, pipeline and integration that calls the old API has its own credential, schedule and owner, and each one breaks differently after the move. Build a complete inventory across every environment before editing a single request. The six cards below cover what to record, where the evidence goes, and how to rehearse the change safely.
Scripts, cron jobs and pipelines
Search every repository, scheduler and automation host for calls to /api/v1, including shell scripts, cron entries, Jenkins or GitLab CI jobs and Airflow DAGs that call their own webserver. Record the file path, owner, schedule and the endpoints each caller uses. Calls hidden inside helper libraries or wrapper images are easy to miss, so search the shared code as well as the callers. Confirm which callers still run at all, because retired jobs should be removed rather than migrated.
Credential type per caller
For each caller, record whether it authenticates with basic auth, a session cookie or a bearer token, and where that secret is stored. Basic auth callers need a token issued through the new auth flow, so each one needs a credential owner and a rotation plan. Note any caller that shares a service account with others, since one token change can break several jobs at once.
OAuth callback URLs on old paths
List every identity provider client, reverse proxy rule and bookmark that points at the pre-3.0 authentication routes. Airflow 3 moves auth routes under /auth, so callback URLs registered with the identity provider must be updated before users can sign in. Record the redirect URI, the client ID and the environment each one serves, so the change can be made in a planned window.
Version and auth manager per environment
Capture the exact Airflow version, the auth_manager setting and the auth provider package in every environment, including development, test, production and disaster recovery. Mixed versions across environments mean different endpoints and auth behavior, so a test result from one environment does not prove another. Record the deployment method too, whether Helm, container images or virtual machines.
Staging that mirrors production auth
Build an Airflow 3 staging environment that uses the same auth manager, identity provider settings and token issuance as production, with test accounts that match production roles. Staging with basic auth or a different identity provider will pass tests that production then fails. Run the inventoried callers against staging and log every failure with its caller ID.
Evidence for change records
Store the inventory, the caller test results, the credential rotation log and the staging run output together under the change record. Auditors and change approvers will ask which callers were tested, against which version, and who approved each credential change. Keep the record alongside the upgrade plan so each caller's status is traceable from inventory to cutover.
Sequence for moving clients from v1 to v2
This sequence moves scripts, CI jobs and integrations from /api/v1 to /api/v2 in a controlled order, so each client changes authentication and routes in staging, is verified against the tests it already passes, and can be rolled back before it goes live.
Confirm the Airflow 3 upgrade path
Confirm the installed Airflow version is 2.7 or later, then move to the latest 2.x patch release, following the upgrade guide's recommendation. Run Ruff AIR301 and AIR302 checks across the DAG repository so that API-adjacent code in DAGs is included in the inventory. Done when the platform team has a written version target and the Ruff report has been reviewed and filed. Rollback: stay on the current 2.x release until the checks are clean, since no client has been changed yet.
Inventory and classify every v1 client
List every script, CI job, scheduled task, DAG-triggered call and third-party integration that calls /api/v1. For each, record the owner, the endpoints used, the authentication method (basic auth or other), whether it uses the Python client, and whether it depends on the /auth route or an OAuth callback. Classify each client as simple (one endpoint, scripted), standard (CI or multi-endpoint) or critical (business-facing or on a production schedule). Done when the inventory is signed off by each owner and every client has a classification. Rollback: not applicable, this step changes nothing.
Switch each client to token authentication in staging
For each classified client, replace basic auth with a bearer token obtained from the token endpoint, usually POST /auth/token, in a staging Airflow 3 environment. Confirm the token scope and lifetime against your auth manager's documentation and your own identity policy before storing credentials in your secrets store. Done when each client authenticates to /api/v2 in staging and the token is retrieved from the secrets backend rather than hardcoded. Rollback: keep the v1 client config in version control so the basic auth version can be restored in staging.
Verify v2 responses against the v1 test suite
Run the same tests used for v1 against /api/v2 in staging and compare results field by field. Pay attention to changed response shapes, removed or renamed parameters and changed pagination, and to any client that relies on run dates or context values removed in Airflow 3. Document each difference and decide whether the client or the test changes. Done when every existing test passes against v2 or each remaining difference has a recorded fix and owner. Rollback: the v1 endpoint remains on the old platform, so the client can be pointed back to it.
Update OAuth callbacks and the /auth prefix
Update any OAuth or SSO callback URLs, and any client that calls authentication routes, so they use the /auth route prefix that Airflow 3 introduces. Confirm the new callback URLs are registered with the identity provider in staging before changing production. Done when a staged sign-in and a staged token request both succeed through the updated routes. Rollback: keep the previous callback registration active until production cutover is complete.
Test credential precedence on Airflow 3.3.2
If the target release is Airflow 3.3.2, test every client for the precedence change: an explicit bearer credential now takes priority over the session cookie, and invalid explicit credentials return 401 or 403 even when a valid cookie is present. Include browser sessions that call the API in the same workflow, and confirm that clients do not send stale tokens. Done when each client returns the expected status for valid and invalid tokens, with and without a session cookie. Rollback: pin the Airflow version to the last release you tested if a client fails and the fix is not yet available.
Cut over client by client with a rollback point
Move production clients one at a time, starting with simple clients and ending with critical ones. Before each cutover, record the current config, token source and last known good run, and confirm the on-call owner. After each switch, check the next scheduled run or a manual call, then compare its output to the v1 baseline. Done when every production client has completed one successful run on v2 and the v1 config is archived. Rollback: restore the saved v1 config for that client only, and keep the other cutovers in place.
Retire the v1 endpoints after the last client
After every client has run successfully on /api/v2 for the agreed observation period, remove v1 configuration from client repositories and secrets stores and record the final inventory state. Confirm no remaining logs or monitors show calls to /api/v1 before turning off any compatibility path. Done when the inventory shows zero active v1 clients and the change record is filed. Rollback: keep archived configs until the record is closed so a late-discovered client can be restored.
What makes API client migrations longer
This table lists the factors that stretch a move from /api/v1 to /api/v2, with why each one adds work and what to confirm before estimating. Read it as a checklist: the more rows that apply to your estate, the more inventory, testing and change control the migration needs.
| Driver | Why it adds effort | What to ask or confirm |
|---|---|---|
| Number and variety of clients | Each script, CI job, dashboard and integration calls the API differently, so each one needs its own inventory entry, owner and cutover step. | Ask for a complete list of callers, including scripts on individual laptops and scheduled jobs that no one currently owns. |
| Basic auth embedded in code or secrets stores | Basic auth credentials must be replaced with token-based authentication, and the same credential may be copied into several places that all need updating. | Confirm where each credential is stored, who can rotate it and whether any client hardcodes it in source control. |
| Custom integrations built on the Python client | Code written against the client library may depend on methods, return shapes or error handling that differ in the newer API, so it needs code changes and retesting. | Ask which client library version each integration pins and whether anyone has tests that cover its calls. |
| OAuth and SSO-linked logins | Auth routes move under the /auth prefix in Airflow 3, so callback URLs and identity provider settings must be changed together with client code. | Confirm which identity provider, which auth manager and which redirect URLs are registered today. |
| Number of environments and change approvals | Each environment needs its own token setup and rollout, and production changes often need a separate review and a maintenance window. | Ask how many environments exist, how promotion works and which teams must sign off a production change. |
| Test coverage for API responses | Without tests that check response fields and status codes, differences only appear when a job fails in production. | Confirm whether existing tests assert on API output and whether a staging Airflow 3 instance is available for replay. |
| Credential precedence behavior in 3.3.2 | In Airflow 3.3.2, an explicit bearer credential takes precedence over the session cookie, and invalid explicit credentials fail with 401 or 403 even when a valid cookie exists. | Confirm which clients send both a bearer token and a session cookie, and test them on the exact patch release you plan to run. |
Questions teams ask before moving Airflow API clients
How much does it cost to move Airflow API clients to v2?
The cost comes from the written scope. DeployOpen does not publish a price list, so a quote follows from the inventory and the work it implies. Ask for the quote to break out each component: inventory and classification of clients, rewriting each script, CI job or integration, setting up token authentication, testing against a staging Airflow 3 server, and handover to the owners. The main drivers are the number of clients, how many languages and CI systems they use, how many embed basic auth or depend on the /auth route, and how many owners must sign off. The migration itself is one-time work. Ongoing upkeep, such as updates after later Airflow 3 patch releases, is a separate decision that can run as a retainer. Ask which items are fixed in the scope and which are priced per client.
How long does migrating Airflow API clients to v2 take?
Duration depends mostly on how many clients exist and how much each one changes. A short list of scripts that only need a new token and a path prefix takes far less time than dozens of CI jobs, each with different owners, secrets and test coverage. Start with an inventory and let it set the schedule. Plan extra time for clients that call endpoints with basic auth in several places, use curl in shell wrappers, or depend on OAuth callback URLs that move under the /auth prefix. Staging tests and owner review often take longer than the code edits. Engagements are fixed-scope, so the timeline is agreed in writing before work starts. Ask for milestones tied to client groups, and confirm which Airflow 3 version you will test against.
What must our team provide before an API v2 migration starts?
Your team has to supply a complete inventory and access to the people and systems that run it. Four items matter most:
- A list of every client calling /api/v1, including scripts, CI jobs, dashboards and third-party integrations, with where each one runs.
- A staging Airflow 3 environment that mirrors production auth settings, so v2 calls can be tested before cutover.
- Service accounts and credential handling: who creates tokens, where they are stored and how they rotate.
- A named owner for each client who can confirm its behavior and approve the change.
Also provide change windows and the current Airflow version and auth manager configuration. Missing owners often delay the work more than the code changes do, so settle them first. Ask DeployOpen to confirm this list in writing as part of the scope.
Can our internal team migrate Airflow API clients without outside help?
Yes, a team can do this alone if it has people who understand Airflow 3 authentication, HTTP APIs and the systems each client runs in. The core skills are reading the Airflow 3 upgrade guide and the auth manager documentation, working with token endpoints such as POST /auth/token, changing scripts and CI secrets safely, writing tests that call a staging server, and tracing failures across pipelines. Someone must also own the credential model, since tokens replace basic auth in many places. Internal teams often underestimate the time spent finding every client. Test each change against the Airflow version you run, and confirm the Python client supports the API version you target before you pin it. If skills or capacity are thin, a fixed-scope engagement can cover the inventory and migration while your team keeps ownership of the clients.
Can we move API clients to v2 before upgrading to Airflow 3?
Confirm this in the upgrade guide before you plan, because /api/v2 is part of Airflow 3 and your test server must run it. In practice, you can prepare clients early by building token handling, updating paths in a branch and writing tests. You cannot verify them against /api/v2 until an Airflow 3 server is available to test. Stand up a staging Airflow 3 instance first, run the client tests there, and keep production on its current release until the cutover window. Read the Airflow 3 upgrade guide for the removed endpoints and auth changes that affect the code you prepare.
What happens to API clients not moved before the Airflow 3 upgrade?
Airflow 3 removes the /api/v1 REST API, so any client still calling it fails once the server is upgraded. Airflow 2 reached end of life on April 22, 2026 and receives no fixes after that date, so staying on 2.x is not a long-term fallback. The failure is often quiet: scripts exit with errors, CI jobs go red on the first run and dashboards stop updating. Integrations that depend on the /auth route or on OAuth callback URLs can break separately if those URLs are not updated. Build the inventory now so unmoved clients are known in advance. Then decide which clients can be cut over, which need a planned fix and which should be retired. Ask for a list of clients not moved by the cutover date, with an owner for each one.
Does the Airflow 3.3.2 credential change break existing API scripts?
It can. In Airflow 3.3.2, released on September 17, 2026, an explicit bearer token takes precedence over the session cookie, and invalid explicit credentials return 401 or 403 even when a valid cookie is present. Clients that send both a bearer header and a cookie, or that reuse a browser session from a wrapper tool, can start failing after the upgrade even though their token looked valid. Check each client for stored or expired tokens, and test it against a 3.3.2 staging server. Refresh tokens through the auth manager where it supports refresh. Log the status code so a 401 or 403 can be traced to the credential first. Add this check to the cutover test list for every client.
How DeployOpen scopes and delivers an API client migration
DeployOpen plans the move from Airflow REST API v1 to v2 as a fixed-scope piece of work inside your own infrastructure. We inventory every script, CI job and integration that calls the API, then build, test and hand over the changed clients with written evidence of what moved.
How we scope
- Inventory every script, CI job and integration that calls /api/v1 on your Airflow instances
- Record which clients use basic auth, which need token authentication, and which depend on the old paths
- Agree in writing which clients, environments and Airflow versions the migration covers
How we build
- Move clients to /api/v2 with token authentication and update any OAuth callback URLs that now sit under /auth
- Test each client against a staging Airflow 3 instance, including the Python client and credential handling
- Check bearer token behavior against the 3.3.2 precedence change before rolling out to shared runners
How we hand over
- Deliver a client inventory with before and after configuration for each migrated integration
- Document token issuance, rotation and where credentials are stored for each client
- Provide test results and a rollback note for each change, agreed before the cutover window
How we support
- Offer ongoing support for later Airflow patch releases and new client integrations as a retainer
- Review client changes when Airflow API behavior changes in later releases
- Agree support boundaries and response expectations in the written scope before work starts
