Cloudflare Scales Developer Platform with Self-Managed OAuth: Decoupling and Executing a Multi-Phase Hydra Upgrade
To enable self-managed OAuth globally, Cloudflare migrated its underlying ORY Hydra engine to version 2.X using a multi-step upgrade path. This technical breakdown details the zero-downtime database migrations, edge-level token coalescing, and queue-based revocation replay systems deployed during the cutover.
Transitioning from API Tokens to Delegated OAuth
Cloudflare has opened self-managed OAuth to all developers, transitioning away from a model previously restricted to manually onboarded integrations. Previously, developers building custom integrations relied on static API tokens, which lacked granular consent controls and presented revocation challenges. To scale delegated access for SaaS integrations, internal developer platforms, and agentic tools, Cloudflare upgraded its underlying OAuth architecture to support scoped, user-managed authorization flows.
Phase 1: Overcoming Schema Locks and SDK Limitations in Hydra 1.X
Cloudflare’s OAuth infrastructure is powered by ORY Hydra, an open-source OAuth engine. Opening the platform to self-managed OAuth required an upgrade from a legacy deployment to Hydra 2.X. To mitigate operational risk, the engineering team divided the migration into two sequential phases: first upgrading to the latest 1.X release, and then proceeding to 2.X.
The initial upgrade to 1.X introduced critical database schema migrations. The default migrations provided by Hydra created indexes that claimed exclusive locks on active database tables, which would block ongoing user OAuth operations. Additionally, the existing Hydra SDK version performed `SELECT *` queries. Introducing new columns or moving columns to new tables during the migration caused deserialization failures within the SDK.
To bypass these failure modes, Cloudflare rewrote the SQL migrations to utilize `CREATE INDEX CONCURRENTLY`. The team also deployed a custom fork of Hydra modified to select explicit columns rather than executing wildcard queries.
Handling Token Invalidation via Edge Coalescing
Although the database migrations executed without immediate user impact, the cutover to the new 1.X version exposed a change in refresh token behavior. The upgraded Hydra release implemented stricter security checks: if a refresh token was reused, Hydra invalidated the entire access and refresh token chain.
This change caused high failure rates for Wrangler and Model Context Protocol (MCP) clients. Because these clients generate high request volumes, network retries frequently resulted in a single refresh token being sent multiple times, invalidating active sessions. Cloudflare mitigated this at the routing layer by adding token coalescing behavior to the Cloudflare Worker routing OAuth traffic. The Worker briefly cached incoming refresh token requests. If it detected a retried request, it responded from the cache without forwarding the duplicate request to Hydra, preventing session invalidation.
Phase 2: Orchestrating a Blue-Green Upgrade to Hydra 2.X
Upgrading from Hydra 1.X to 2.X introduced schema changes too extensive for an in-place migration. A blue-green deployment strategy was required, but the system had to remain write-enabled during the migration window to allow continuous token authorization and revocation.
To minimize write volume during the migration, Cloudflare temporarily extended token expiration times to several hours, preventing applications from needing to refresh tokens during the transition. To handle user revocations without losing data, the team implemented a queue-based ingestion pipeline.
During the migration window, any user revocation event was captured and written to a queue using Cloudflare Queues. Once the database was cut over to the new green target, the queue was drained, replaying the captured revocations against the active database. This prevented revoked applications from having their permissions inadvertently restored.
- Enabling the revocation capture queue.
- Cloning and restoring the production database to the new target.
- Performing targeted data cleanup to resolve legacy data constraints incompatible with 2.X schemas.
- Running the Hydra migrations on the target database, which took approximately three hours.
- Executing a synchronized cutover of the Hydra service and two dependent internal configuration systems.
Mitigating Post-Migration State Discrepancies
Following the 2.X cutover, Cloudflare observed an elevated rate of 403 errors. Investigation revealed that an active data cleanup job in the primary authorization service was purging OAuth policy data.
This cleanup was triggered by a bug in one of Hydra's 2.X migrations, which corrupted the state of certain valid OAuth sessions, causing them to be marked as invalid. When the authorization service queried Hydra's consent session API, it received mismatched state data and purged the corresponding policies. To resolve the issue, Cloudflare restored the corrupted session data and initiated architectural changes to decouple the authorization service from static policy data dependencies.