The Convex Secret Sync requires a Convex app connection. This guide walks you through creating a project-scoped app connection.
Prerequisites
- A project with secrets configured
- A Convex account with a deployment you can manage
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.

2
Under Personal Access Tokens, select + Create Token.

3
Enter a Token Name, such as 
infisical, pick an Expiration, then select Create.
4
Copy the token and store it securely. Convex shows it only once, and you need it to create the connection in Infisical.

Step 2: Set up the sync in Infisical
1
In your project, go to Integrations and open the Secret Syncs tab. Select + Add Sync.
Then, select the Convex sync.
Then, select the Convex sync.2
Under Source, choose which secrets to sync from Infisical:Then select Continue.
- 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_URLorCONVEX_SITE_URL, which Convex sets on every deployment
3
Under Destination, create or select the Convex app connection the sync will use, then choose the deployment that receives the secrets.
- Create a new app connection
- Use an existing connection
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)
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)
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
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
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.