Cloudflare Workers

How it works

The Cloudflare integration pushes your keys into a Worker's secrets and its build variables. Syncing runs on the same triggers as Vercel: key changes when auto-sync is on, the retry sweep, and Sync now, which previews every change first. Workers are supported; Pages projects are not yet.

Connecting Cloudflare

On Integrations, click Connect Cloudflare. Cloudflare asks you to pick one or more accounts and approve ApiVault's access to their Workers, then sends you back to the project's Cloudflare page. One approval is one connection, however many accounts it covers. To add more, click Connect Another Cloudflare Account, with the same Cloudflare login or a different one. If every account you pick is already connected, nothing changes. An approval for other accounts becomes its own connection and leaves the first one as it was. One that adds an account to everything a connection already has updates that connection instead. ApiVault hands back any approval it doesn't keep. Reconnect always replaces the connection it belongs to.

Linking a Worker and its targets

Click Add Worker on the connection, choose the account and the Worker, then tick which targets each ApiVault environment goes to:

• Production — the Worker's secrets. Cloudflare deploys a new Worker version whenever they change, so ApiVault batches a sync's changes into as few writes as it can (usually one deployment) and applies this target last.
• Previews — the secrets every Preview starts from. Changes apply to Previews created after the sync.
• Build · Production and Build · Previews — secret build variables for Workers Builds on your production branch and on other branches. They take effect at the next build; ApiVault does not start one.

ApiVault suggests production or prod → Production and preview, staging or stage → Previews; anything else starts unmapped. A target can come from only one environment. Wrangler environments such as [env.staging] deploy separate Workers (my-api-staging), so link each one. To change the targets later, choose Edit mapping in the link's ⋯ menu.

A target the Worker doesn't offer is greyed out, with the reason:

• Previews aren't enabled for this Worker.
• Build variables need a Git repository connected to the Worker in Cloudflare.
• Build · Previews also needs preview builds, which you turn on in Cloudflare under Settings › Build › Branch control.

What ApiVault changes in Cloudflare

Cloudflare does not record who created a secret, so ApiVault keeps its own list of what it created for each link and target, and only ever updates or deletes those. Anything else with the same name on a target — a secret, plain variable or binding you created, or a plain build variable — is a conflict: the key is skipped on that target only, and the others still sync. Delete or rename your copy in Cloudflare, then click Sync now.

Cloudflare never shows secret values back, so ApiVault can't see an edit made in the dashboard. The next change to the key in ApiVault overwrites it, and a secret deleted in Cloudflare is created again on the next sync.

A key's name is used exactly. Names must start with a letter or underscore and contain only letters, digits and underscores; build targets also reserve CI and names starting with WORKERS_CI, which Workers Builds sets itself. Values over 5 KiB are skipped without being sent. How many variables a Worker may hold depends on your Cloudflare plan: when Cloudflare refuses more, the keys it refused are reported as over limit and the rest are still sent.

Gradual deployments

While a Worker's latest version is only partly deployed, Cloudflare refuses changes to its secrets. The link shows Retrying with "Cloudflare refused the change because the Worker's latest version isn't fully deployed. Finish or roll back the gradual deployment." ApiVault keeps retrying; after ten failures in a row it stops and notifies owners and admins.

Access, custom vault keys and removal

Projects with a custom vault key work as they do for Vercel: auto-sync is off, and Sync now asks for the key. If you revoke ApiVault in Cloudflare (Profile → Manage OAuth authorizations), the connection shows Access lost, its links show Action needed and owners and admins are notified; click Reconnect to resume. If an account is left out of a new approval, its Workers show Action needed until you connect again and include it. A target that stops being available is reported as Unavailable on the link while the other targets keep syncing.

Unlink deletes the secrets and build variables ApiVault created on every target, then removes the link; deleting production secrets deploys a new Worker version. Disconnect unlinks every Worker and then hands back that project's Cloudflare tokens. Each project's connection is its own approval, so another ApiVault project connected with the same Cloudflare login keeps working. If ApiVault can't reach the account, Remove anyway lists what stays in Cloudflare. The statuses match Troubleshooting by status, with Cloudflare in place of Vercel.

Handing the tokens back stops ApiVault reaching your account, but Cloudflare still lists the application under My Profile → Access Management → Connected Applications, because it keeps the approval itself separate from the tokens issued against it. To clear that entry too, select Revoke there; that cuts off every ApiVault project connected with that Cloudflare login.