> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Secrets
> Store API keys and other credentials as secrets, give each environment its own value, and reference them from tools without exposing the value.
Secrets let you securely store sensitive information like API keys, database credentials, and encryption keys. Unlike variables, secret values are encrypted and hidden from view, keeping your credentials safe while still allowing your agent to use them. A secret's name is shared across your whole project; its value belongs to each [environment](/docs/documentation/deploy/environments/overview).
## Creating secrets
Open **Secrets** in your agent's navigation and click **New secret** in the top right.
When creating a secret, you'll provide a name, value, and visibility setting:
- **Masked** secrets are hidden by default but can be temporarily revealed by clicking on them.
- **Restricted** secrets cannot be revealed after creation. Use this for highly sensitive credentials.
The value you enter is stored in the environment you have open. Every other environment picks up the new secret's name right away, but not its value, and shows a **Missing value** warning on that secret until you set a value there too.
You can also create secrets inline while building. Type `{` in any input field, switch to the **Secrets** tab in the dropdown, then click **Create secret** at the bottom.
## Using secrets
Secrets work like variables but are accessed from a separate tab. In any input field within a [tool](/docs/documentation/build/tools/api-tool), type `{` to open the dropdown, then switch to the **Secrets** tab and select the secret you need.
Which value your agent sends depends on the version that handles the conversation. Every environment holds two values for each secret:
| Column | What uses it |
| --- | --- |
| **Default value** | Used by this environment's published version, and by its draft version if no draft value is set. |
| **Draft value** | Used by this environment's draft version. Leave empty to use the default value. |
**Default value** is the value this environment uses. Previews and test conversations run against the draft version, so they send the **Draft value** when one is set and the **Default value** when it isn't. Your live agent only ever sends the **Default value**.
## Secrets in each environment
The **Secrets** page always shows the environment you have open. Use the environment switcher at the top of the sidebar to move to another environment and see the values it holds.
Next to each secret's name are its **Default value**, its **Draft value**, and **Updated**, which shows when that secret's value was last edited in this environment. Publishing, merging, or cloning doesn't change it: a value copied into a new version or environment keeps the time it was edited.
An environment that has no value for a secret shows a **Missing value** warning on that row. Because every environment holds its own values, a secret you set up in one environment needs a value in every other environment that uses it.
## Managing secrets
Click the three dots next to a secret for **Copy value**, **Edit**, and **Delete**. For masked secrets, **Copy value** copies this environment's default value to your clipboard. Restricted secrets cannot be copied or revealed.
**Edit** opens the same dialog you created the secret with, for the environment you have open. Enter a new **Default value** to replace this environment's value; leave the field empty to keep the value it has. To stop using a **Draft value**, click **Clear draft value** under the field and save; the draft version goes back to using the default value.
**Delete** removes the secret and every environment's values for it, and can't be undone. Delete a secret only when nothing anywhere in the project still needs it.
### When a value is missing
When a tool references a secret that the environment has no value for, your agent sends the placeholder text exactly as written: a header entered as `Bearer {my_api_key}` goes out as `Bearer {my_api_key}`. The service you're calling rejects it, usually with a 401, the step takes its failure path, and the conversation continues. Nothing warns you at run time, so a missing value looks like an ordinary API failure until you check the secret's row for the **Missing value** warning.
## Publishing, reverting and discarding changes
[Publishing](/docs/documentation/deploy/environments/publishing), reverting, and discarding changes act on your agent's content. Here is what each one does to an environment's secret values.
| Action | What happens to secret values |
| --- | --- |
| **Publish** | The new live version keeps using the environment's **Default value**. The **Draft value** stays a draft value; publishing never turns it into the default. |
| **Revert** | [Reverting](/docs/documentation/deploy/environments/version-history) restores content, not credentials. The environment keeps the secret values it has now, so a key you rotated stays rotated. |
| **Discard changes** | The draft's content is discarded. The environment keeps its **Draft value**. |
## Testing with a non-production credential
A **Draft value** lets an environment's draft version call a sandbox service while its live version keeps calling the real one.
Use the environment switcher at the top of the sidebar, then open **Secrets**.
Edit the secret, enter the sandbox key in **Draft value**, and leave **Default value** as the production credential.
Previews and test conversations run against the draft version, so they use the sandbox key. The live version of this environment, and every other environment, is unaffected.
Edit the secret, click **Clear draft value** under **Draft value**, and save. If you merge this environment into `Main` and choose to override `Main`'s secrets, both values are carried, and a sandbox key left in **Draft value** would become `Main`'s draft value.
## Merging to Main
By default, [merging](/docs/documentation/deploy/environments/merging) an environment into `Main` leaves `Main`'s secret values alone. When the source environment's values differ from `Main`'s, the merge dialog tells you: "This environment has different secret values than Main, select how to proceed." Turn on **Override Main secrets** to replace `Main`'s values with the source environment's, both the **Default value** and the **Draft value**. A secret the source environment has no value for is removed from `Main` too, which leaves `Main` with no value for it.
The dialog never shows the values themselves, only that they differ. Before you confirm with **Override Main secrets** on, make sure the source environment's **Default value** is the production credential, because it becomes the value `Main`'s live version uses. A sandbox key left in **Draft value** only reaches `Main`'s draft version; clear it first if you don't want it there.
## Duplicating and exporting projects
**Duplicate project** copies your secrets, with the **Default value** and **Draft value** they hold in `Main`, when the copy stays in your workspace. A copy made in another workspace, for example through **Copy clone link**, and an exported project carry secret names only. After importing, set the values in each environment that needs them.
## Security
Secrets are encrypted using AES-256 GCM, which provides both confidentiality and integrity protection through a Message Authentication Code (MAC). Encryption keys are securely managed and secrets are stored and transmitted according to industry best practices.