Vercel

Connecting Vercel

Open your project, go to Integrations and click Connect Vercel. Vercel asks you to choose your personal account or a team, and whether ApiVault may see all projects or only the ones you select. When you approve, Vercel sends you back to the project's Vercel page.

To sync to projects in another Vercel account or team, click Connect Another Team at the bottom of the Vercel page. Each team gets its own connection.

Linking a Vercel project

On the Integrations page, click Manage on the Vercel card to open your Vercel connections, then click Add Project on the connection. First search for and choose the Vercel project, then tick which Vercel targets each environment goes to and set the options. One ApiVault project can feed several Vercel projects, each with its own mapping and options.

Environment mapping

Production, Staging and Development are always listed, even before they hold keys, along with any other environment your keys use. Each can be sent to any of Vercel's three targets: production, preview and development. ApiVault suggests a mapping from the environment's name:

• production or prod → production
• preview, staging or stage → preview
• development, dev or local → development

Anything else starts unmapped, and its keys are not sent. A Vercel target can come from only one environment — otherwise the same variable would have two values — and at least one environment must be mapped.

What ApiVault changes

ApiVault only ever creates, updates and deletes the variables it created. Vercel tags each one with the integration that made it, and ApiVault checks that tag before touching anything. Variables you added in Vercel yourself are never modified or deleted. If two ApiVault projects sync to the same Vercel project through one team, each only changes the variables it created, and a variable the other project created with the same name is reported as a conflict.

If you already have a variable in Vercel with the same name on an overlapping target, ApiVault skips that key for the link and reports a conflict. Delete or rename your copy in Vercel, then click Sync now to let ApiVault take it over.

Deleting a key in ApiVault deletes the variable ApiVault created for it. Editing a variable ApiVault owns directly in Vercel is overwritten on the next sync.

Variable names

A key's name is used as the variable name exactly, as with apivault run. Names must start with a letter or underscore, contain only letters, digits and underscores, and must not start with VERCEL_, which Vercel reserves. Keys with other names are skipped and listed in the sync's issues — rename the key in ApiVault to include it.

Sensitive and encrypted variables

Variables sent only to production or preview are created as Sensitive, so nobody can read them back in Vercel's dashboard. Vercel does not allow sensitive variables on the development target, so a variable that includes development is created as Encrypted.

Projects with a custom vault key

In custom encryption mode the server cannot decrypt your keys on its own, so it cannot sync in the background. Auto-sync is off and cannot be turned on. Click Sync now and enter the vault key: the sync runs within that request, and the key is not stored, logged or kept for a later retry.

Switching a project to custom mode turns auto-sync off on all of its links.

Redeploying on change

Vercel reads environment variables at build time, so a changed value reaches a live deployment only after it is rebuilt. Turn on Redeploy production on change for a link and, whenever a sync changes a production variable, ApiVault redeploys the latest ready production deployment. It is off by default.

A redeploy that fails does not undo the sync. It is reported as an issue on the link, and the variables stay updated.

Sync now and previews

Sync now first compares ApiVault with Vercel and shows what would change, grouped as Create, Update, Delete, Conflicts and Skipped. Only names and targets are shown, never values. Nothing is written until you click Apply.

The preview reflects Vercel at that moment. If Vercel changes before you apply, ApiVault does not apply the old plan — it shows the new one and asks you to review again.

Sync now works regardless of auto-sync, retry delays or an Action needed status, and a successful run clears the failure count.

Unlinking and disconnecting

Both actions are in the ⋯ menu: a linked project's menu holds Unlink, and the connection's menu holds Disconnect.

Unlink deletes every variable ApiVault created in that Vercel project, then removes the link. If Vercel cannot be reached, the link shows Removing… N left and ApiVault keeps retrying, so it never forgets a variable it still owns. When Vercel refuses ApiVault's access altogether, retrying cannot help: ApiVault asks whether to Remove anyway instead of waiting.

Disconnect unlinks every project on the connection the same way, then removes ApiVault from your Vercel account or team. If another ApiVault project is connected to the same account or team, they share one installation, so it stays until the last of them disconnects.

If ApiVault is removed from your Vercel account or team on Vercel's side, Vercel deletes the variables ApiVault created and syncing stops. Reconnect to sync again, or unlink the projects to clear them from ApiVault.

Troubleshooting by status

Each link shows a status. View details lists the last sync's issues by key, and every sync is recorded in the project's audit log under Integrations. A sync that ends in an error is recorded as a failed sync. Connecting, linking, editing, unlinking and disconnecting are recorded too, including attempts that fail; a disconnect is one entry rather than one per linked project, and an unlink or disconnect that finishes in the background adds a Finished entry.

• Not synced yet — the link is new, or auto-sync is off. Click Sync now.
• Syncing — a sync is running. The page refreshes when it finishes.
• Synced — everything mapped is in Vercel.
• Conflict — the sync finished, but some keys were skipped: a variable you created in Vercel has the same name, or the key's name is not a valid variable name. Fix it, then click Sync now. Conflicts are not retried automatically, because retrying cannot fix them.
• Retrying — Vercel returned an error or was unreachable. ApiVault retries on its own, waiting longer after each failure, up to six hours between attempts.
• Action needed — ApiVault stopped retrying. The Vercel project was deleted or is no longer shared with ApiVault, the connection was revoked or disabled on Vercel, or ten attempts in a row failed. Owners and admins are notified. Fix the cause — reconnect, or share the project with ApiVault again in Vercel — then click Sync now.
• Removing… N left — an unlink is still deleting variables. It retries on its own; see Unlinking and disconnecting.