> ## Documentation Index
> Fetch the complete documentation index at: https://infisical.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Convex sync

> Learn how to configure a Convex sync for Infisical.

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.

> [!NOTE]
>
> The Convex Secret Sync requires a [Convex app connection](https://infisical.com/docs/integrations/app-connections/convex.md). This guide walks you through creating a project-scoped app connection.

## Prerequisites

* A [project with secrets configured](https://infisical.com/docs/documentation/platform/secrets-mgmt/quick-starts/deliver-first-secret.md)
* A [Convex account](https://dashboard.convex.dev) 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.

**Step 1**

In the [Convex Dashboard](https://dashboard.convex.dev), select your profile avatar, then select **Profile Settings**.

![Profile Settings](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/app-connections/convex/01-profile-settings.png)

**Step 2**

Under **Personal Access Tokens**, select **+ Create Token**.

![Create Token](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/app-connections/convex/02-create-token.png)

**Step 3**

Enter a **Token Name**, such as `infisical`, pick an **Expiration**, then select **Create**.

> [!WARNING]
>
> 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](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/app-connections/convex/03-fill-and-create-token.png)

**Step 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](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/app-connections/convex/04-copy-token.png)

## Step 2: Set up the sync in Infisical

> [!TIP]
>
> To create the sync using the API, use the Convex [Create](https://infisical.com/docs/api-reference/endpoints/secret-syncs/convex/create.md) endpoint.

**Step 1**

In your project, go to **Integrations** and open the **Secret Syncs** tab. Select **+ Add Sync**.

![Secret Syncs Tab](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/secret-syncs/general/secret-sync-tab.png)

Then, select the **Convex** sync.

**Step 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

> [!NOTE]
>
> 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.

> [!TIP]
>
> If you need to sync secrets from multiple folder locations, use [secret imports](https://infisical.com/docs/documentation/platform/secret-reference.md#secret-imports).

Then select **Continue**.

**Step 3**

Under **Destination**, create or select the Convex app connection the sync will use, then choose the deployment that receives the secrets.

> [tab] Create a new app 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](#step-1-create-a-personal-access-token-in-convex)
> * **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.
>
> > [!NOTE]
> >
> > This creates a connection scoped to the current project. To share the connection across other projects, [create it at the organization level](https://infisical.com/docs/integrations/app-connections/convex.md#setup-convex-connection-in-infisical) first, then select it here.

> [tab] Use an existing connection
>
> Under **Convex Connection**, select the app connection you'd like to use.

* **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**.

**Step 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**.

**Step 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

> [!WARNING]
>
> 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**.

**Step 6**

Give the sync a **Name** and an optional **Description**. The name must be slug-friendly.

Then select **Continue**.

**Step 7**

Review your Convex Sync configuration, then select **Create Sync**.

> [!TIP]
>
> The sync is created. If **Auto-sync on changes** is enabled, it begins syncing secrets to your Convex deployment right away.

## Next steps

> [card] [Convex](https://infisical.com/docs/integrations/app-connections/convex.md)
>
> Create a Convex connection at the organization level to share it across projects.

> [card] [Overview](https://infisical.com/docs/integrations/secret-syncs/overview)
>
> See every destination you can sync secrets to.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.