---
layout: docs
page_title: Sync secrets from Vault to Vercel Project
description: >-
  Automatically sync and unsync the secrets from Vault to a Vercel project to centralize visibility and control of secrets lifecycle management.
---

# Sync secrets from Vault to Vercel Project

The Vercel Project sync destination allows Vault to safely synchronize secrets as Vercel environment variables.
This is a low footprint option that enables your applications to benefit from Vault-managed secrets without requiring them
to connect directly with Vault. This guide walks you through the configuration process.

Prerequisites:
* Ability to read or create KVv2 secrets
* Ability to create Vercel tokens with access to modify project environment variables
* Ability to create sync destinations and associations on your Vault server

## Setup

1. If you do not already have a Vercel token, navigate [your account settings](https://vercel.com/account/tokens) to
   generate credentials with the necessary permissions to manage your project's environment variables.

1. Next you need to locate your project ID. It can be found under the `Settings` tab in your project's overview page.

1. Configure a sync destination with the access token and project ID obtained in the previous steps.

  ```shell-session
  $ vault write sys/sync/destinations/vercel-project/my-dest \
      access_token="$TOKEN" \
      project_id="$PROJECT_ID" \
      deployment_environments=development \
      deployment_environments=preview \
      deployment_environments=production
  ```

  **Output:**

  <CodeBlockConfig hideClipboard>

  ```plaintext
  Key                   Value
  ---                   -----
  connection_details    map[access_token:***** deployment_environments:[development preview production] project_id:<project-id>]
  name                  my-dest
  type                  vercel-project
  ```

  </CodeBlockConfig>

## Usage

1. If you do not already have a KVv2 secret to sync, mount a new KVv2 secrets engine.

  ```shell-session
  $ vault secrets enable -path='my-kv' kv-v2
  ```

  **Output:**

  <CodeBlockConfig hideClipboard>

  ```plaintext
  Success! Enabled the kv-v2 secrets engine at: my-kv/
  ```

  </CodeBlockConfig>

1. Create secrets you wish to sync with a target Vercel project.

  ```shell-session
  $ vault kv put -mount='my-kv' my-secret key1='val1'
  ```

  **Output:**

  <CodeBlockConfig hideClipboard>

  ```plaintext
  ==== Secret Path ====
  my-kv/data/my-secret

  ======= Metadata =======
  Key                Value
  ---                -----
  created_time       <timestamp>
  custom_metadata    <nil>
  deletion_time      n/a
  destroyed          false
  version            1
  ```

  </CodeBlockConfig>

1. Create an association between the destination and a secret to synchronize.

  ```shell-session
  $ vault write sys/sync/destinations/vercel-project/my-dest/associations/set \
    mount='my-kv' \
    secret_name='my-secret'
  ```

  **Output:**

  <CodeBlockConfig hideClipboard>

  ```plaintext
  Key                   Value
  ---                   -----
  associated_secrets    map[kv_1234/my-secret:map[accessor:kv_1234 secret_name:my-secret sync_status:SYNCED updated_at:<timestamp>]]
  store_name            my-dest
  store_type            vercel-project
  ```

  </CodeBlockConfig>

1. Navigate to your project's settings under the `Environment Variables` section to confirm your secret was successfully
  created in your Vercel project.

Moving forward, any modification on the Vault secret will be propagated in near real time to its Vercel environment variable
counterpart. Creating a new secret version in Vault will overwrite the value in your Vercel Project. Deleting the secret
or the association in Vault will delete the secret on Vercel as well.

<Note>

Vault syncs secrets differently depending on whether you have configured 
`secret-key` or `secret-path` [granularity](/vault/docs/sync#granularity):

- `secret-key` granularity splits KVv2 secrets from Vault into key-value pairs
  and stores the pairs as distinct entries in Vercel. For example,
  `secrets.key1="val1"` and `secrets.key2="val2"`.

- `secret-path` granularity stores secrets as a single JSON string that contains
  all the associated key-value pairs. For example, `{"key1":"val1", "key2":"val2"}`.

Since Vercel projects limit environment variables to single-value secrets, the
sync granularity defaults to `secret-key`.

</Note>

## API

Please see the [secrets sync API](/vault/api-docs/system/secrets-sync) for more details.
