Skip to main content
A Convex Secret Sync pushes secrets from Infisical into a Convex deployment’s environment variables, where your Convex functions read them at runtime. Each Infisical secret becomes a Convex environment variable with the same name, unless you customize key names to add a prefix or suffix.
The Convex Secret Sync requires a Convex app connection. This guide walks you through creating a project-scoped app connection.

Prerequisites

Step 1: Create a personal access token in Convex

Infisical authenticates to Convex with a personal access token that can list deployments and manage their environment variables.
1
In the Convex Dashboard, select your profile avatar, then select Profile Settings.Profile Settings
2
Under Personal Access Tokens, select + Create Token.Create Token
3
Enter a Token Name, such as infisical, pick an Expiration, then select Create.
If the token expires, Infisical can’t use the connection until you replace the token. Set a long expiration, or select No expiration.
Fill and Create Token
4
Copy the token and store it securely. Convex shows it only once, and you need it to create the connection in Infisical.Copy Token

Step 2: Set up the sync in Infisical

To create the sync using the API, use the Convex Create endpoint.
1
In your project, go to Integrations and open the Secret Syncs tab. Select + Add Sync.Secret Syncs TabThen, select the Convex sync.
2
Under Source, choose which secrets to sync from Infisical:
  • Environment: The project environment to retrieve secrets from
  • Secret Path: The folder path to retrieve secrets from
  • Include secrets from all subfolders: Also syncs the secrets in every folder beneath the path
Convex rejects an environment variable name if any of the following is true:
  • The name starts with a digit, or contains a character other than a letter, a digit, or an underscore
  • The name is longer than 256 characters
  • The name is CONVEX_CLOUD_URL or CONVEX_SITE_URL, which Convex sets on every deployment
If any secret has a name Convex rejects, the sync fails without writing any secrets, and the error names each rejected secret.
If you need to sync secrets from multiple folder locations, use secret imports.
Then select Continue.
3
Under Destination, create or select the Convex app connection the sync will use, then choose the deployment that receives the secrets.
Under Convex Connection, select Create Connection in the dropdown, then fill in:
  • Name: A descriptive name for the connection, such as convex-prod
  • Description (optional): A note for future reference
  • Method: Personal Access Token (selected by default)
  • Access Token: The token you copied when you created the personal access token
  • Instance URL (optional): The Convex API URL (leave this empty to use https://api.convex.dev)
Select Connect to Convex. Infisical returns you to the sync form with the new connection selected.
This creates a connection scoped to the current project. To share the connection across other projects, create it at the organization level first, then select it here.
  • Deployment: The Convex deployment to sync secrets to, from the cloud deployments the connection can access (local deployments aren’t listed, because Infisical can’t reach them)
Then select Continue.
4
Under Initial Sync Behavior, choose how Infisical handles environment variables that already exist in the Convex deployment on the first sync:
  • Overwrite Destination Secrets: Infisical writes its secrets to the deployment without importing anything first
  • Import Destination Secrets - Prioritize Infisical Values: Infisical first imports the deployment’s environment variables; if a name exists in both places, Infisical keeps its own value
  • Import Destination Secrets - Prioritize Convex Values: Infisical first imports the deployment’s environment variables; if a name exists in both places, the Convex value replaces the Infisical value
Then select Continue.
5
Under Sync Options, choose how secrets are synced:
  • Prevent secret deletion: When enabled, Infisical adds and updates environment variables in Convex but never deletes them; enable this if you manage some Convex environment variables outside of Infisical
  • Auto-sync on changes: When enabled, secrets sync to Convex automatically as the source changes; turn it off to sync manually only
  • Customize key names: Adds a prefix or suffix to every synced name, using {{secretKey}} for the original name and {{environment}} for the environment slug
Convex environment variables belong to the whole deployment, so a sync can change environment variables that were created outside Infisical. If you don’t customize key names, the sync treats every environment variable in the deployment as one it manages:
  • If a Convex environment variable has the same name as an Infisical secret, the sync overwrites the Convex environment variable’s value
  • If Prevent secret deletion is off, every Convex environment variable that isn’t in Infisical is deleted
With customized key names, the sync writes only names with your prefix or suffix, and deletes only Convex environment variables whose names match it.Before the first sync, customize key names or keep Prevent secret deletion on. Prevent secret deletion is on by default when you create the sync in the UI, but off unless you set disableSecretDeletion when you create it through the API.
Then select Continue.
6
Give the sync a Name and an optional Description. The name must be slug-friendly.Then select Continue.
7
Review your Convex Sync configuration, then select Create Sync.
The sync is created. If Auto-sync on changes is enabled, it begins syncing secrets to your Convex deployment right away.

Next steps

Convex

Create a Convex connection at the organization level to share it across projects.

Overview

See every destination you can sync secrets to.