---
title: Secrets
description: Manage API keys and environment variables for your workflows
---

import { Callout } from 'fumadocs-ui/components/callout'
import { Image } from '@/components/ui/image'
import { FAQ } from '@/components/ui/faq'

Secrets are key-value pairs that store sensitive data like API keys, tokens, and passwords. Instead of hardcoding values into your workflows, you store them as secrets and reference them by name at runtime.

## Managing Secrets

To manage secrets, open your workspace **Settings** and navigate to the **Secrets** tab.

<Image
  src="/static/secrets/secrets-list.png"
  alt="Secrets tab showing Workspace and Personal sections with inline key-value rows"
  width={700}
  height={500}
/>

Secrets are organized into two sections:

- **Workspace** — shared with all members of your workspace
- **Personal** — private to you

External workspace members count as workspace members for workspace-scoped secrets. They can use workspace secrets according to their workspace permission level, even though they are not members of your organization.

### Adding a Secret

Type a key name (e.g. `OPENAI_API_KEY`) into the **Key** column and its value into the **Value** column in the last empty row. A new empty row appears automatically as you type. Existing values are masked by default.

When you're done, click **Save** to persist all changes.

<Callout type="info">
Keys must use only letters, numbers, and underscores — no spaces or special characters.
</Callout>

### Bulk Import

You can populate multiple secrets at once by pasting `.env`-style content into any key or value field. The parser supports standard `KEY=VALUE` pairs, `export KEY=VALUE`, quoted values, and inline comments.

### Editing and Deleting

Click directly into any key or value cell to edit it. To delete a secret, click the trash icon on its row and save.

## Using Secrets in Workflows

To reference a secret in any input field, type `{{` to open the variable dropdown. Your available secrets are listed grouped by scope (workspace, then personal).

<Image
  src="/static/credentials/secret-dropdown.png"
  alt="Typing {{ in an input opens a dropdown showing available secrets"
  width={400}
  height={250}
/>

Select the secret you want to use. The reference appears highlighted in blue and is resolved to its actual value at runtime.

<Image
  src="/static/credentials/secret-resolved.png"
  alt="A resolved secret reference shown as {{OPENAI_API_KEY}}"
  width={400}
  height={200}
/>

<Callout type="warn">
Secret values are never exposed in the workflow editor or execution logs — they are only resolved during execution.
</Callout>

## Secret Details

Click **Details** on any secret row to open its detail view.

<Image
  src="/static/secrets/secret-details.png"
  alt="Secret details view showing Display Name, Description, and Members sections"
  width={700}
  height={400}
/>

From here you can:

- Edit the **Display Name** and **Description**
- Manage **Members** — invite teammates by email and assign them an **Admin** or **Member** role

Click **Save** to apply changes, or **Back** to return to the list.

## Workspace vs. Personal

| | Workspace | Personal |
|---|---|---|
| **Visibility** | All workspace members, including external workspace members | Only you |
| **Use in workflows** | Any member can use | Only you can use |
| **Best for** | Production workflows, shared services | Testing, personal API keys |
| **Who can edit** | Workspace admins | Only you |

<Callout type="info">
When a workspace secret and a personal secret share the same key name, the **workspace secret takes precedence**.
</Callout>

### Resolution Order

When a workflow runs, secrets resolve in this order:

1. **Workspace secrets** are checked first
2. **Personal secrets** are used as a fallback — from the user who triggered the run (manual) or the workflow owner (automated runs via API, webhook, or schedule)

## Best Practices

- **Use workspace secrets for production** so workflows work regardless of who triggers them
- **Use personal secrets for development** to keep test keys separate
- **Name keys descriptively** — `STRIPE_SECRET_KEY` over `KEY1`
- **Never hardcode secrets** in workflow input fields — always use `{{KEY}}` references

<FAQ items={[
  { question: "Are my secrets encrypted at rest?", answer: "Yes. Secret values are encrypted before being stored in the database using server-side encryption, so raw values are never persisted in plaintext. They are also never exposed in the workflow editor, logs, or API responses." },
  { question: "What happens if both a workspace secret and a personal secret have the same key name?", answer: "The workspace secret takes precedence. During execution, the resolver checks workspace secrets first and uses personal secrets only as a fallback. This ensures production workflows use the shared, team-managed value." },
  { question: "Who determines which personal secret is used for automated runs?", answer: "For manual runs, the personal secrets of the user who clicked Run are used as fallback. For automated runs triggered by API, webhook, or schedule, the personal secrets of the workflow owner are used instead." },
  { question: "Can I import secrets from a .env file?", answer: "Yes. Paste .env-style content (KEY=VALUE format) into any key or value field and the secrets will be auto-populated. The parser supports export KEY=VALUE, quoted values, and inline comments." },
  { question: "What happens if I delete a secret that is used in a workflow?", answer: "The workflow will fail at any block that references the deleted secret during execution because the value cannot be resolved. Update any references before deleting a secret." },
]} />
