# Secret store

> Falak's secret store: scopes, ${{ secrets.NAME }} references, sensitive secrets, versions and rollback, reveal, and how secrets reach servers.

Source: https://falak.sh/docs/secrets/secret-store/

Since v0.10.0 Falak has a **secret store**: named secrets with immutable versions, an access log, and optional links to an external provider (Vault, AWS, 1Password, Doppler, Infisical or your own HTTPS endpoint). Sites read them with `${{ secrets.NAME }}` references, so a value lives in one place and never has to be copied into each site.

## Scopes

A secret belongs to one scope. Names are environment variable names (`^[A-Z_][A-Z0-9_]*$`), unique per scope.

| Scope | Where to manage it | Seen by |
|---|---|---|
| Organization | **Settings → Secrets** | every service of the organization |
| Project | Project **Settings → Secrets** | every service of the project |
| Environment | Project **Settings → Secrets** | the services of one environment |
| Service | Project **Settings → Secrets** | one service |

A reference resolves to the **nearest** secret of that name: the service's own, then its environment's, its project's, then the organization's. So a project secret can override an organization default, and a `production` secret can override the project's.

## Create a secret

1. Open **Settings → Secrets** (organization) or the project's **Settings → Secrets**, then **New secret**.
2. Fill in:

   | Field | Meaning |
   |---|---|
   | Name | Capital letters, digits and underscores, like an environment variable |
   | Scope | Organization, project, environment or service |
   | Source | **Value** (stored in Falak) or **Linked to a provider** (see [Secret providers](/docs/secrets/providers/)) |
   | Sensitive | On by default. Write-only: once saved, no one can read the value back, only replace it |
   | Available to preview environments | Off by default. Only these secrets reach [preview environments](/docs/guides/preview-environments/) |
   | Rotate every | Days. Flags the secret, and fires `secrets.rotation_due`, when its value is older |
   | Description | Optional |

3. Save.

## Use it in a site

Reference the secret from a site's variables:

```dotenv
STRIPE_SECRET=${{ secrets.STRIPE_SECRET }}
```

It resolves at deploy time, like [other references](/docs/guides/variable-references/). A secret that doesn't exist fails the deployment before anything changes on your servers:

```text title="Example deployment error"
STRIPE_KEY: secret STRIPE_KEY is not defined for this service …
```

Each read is recorded in the secret's **access log** (once per deployment and version): who or what read which version, and why.

### Promote a variable

A plain variable can become a secret in one step: **Promote a variable to a secret** on the Secrets page. Pick the service and the variable, name the secret, and choose whether it is sensitive. The value moves into a new secret of that service, and the variable becomes `${{ secrets.NAME }}` — in its current version and every older one, so restoring an old environment version can't bring the value back. Only plain values can be promoted, not `${{ … }}` references.

## Versions and rollback

Every new value is a new **immutable version**; the history is never rewritten. A new value is used from the next deployment.

- **Roll back** to a version: Falak creates a new version holding that version's value.
- **Disable** a version: it can no longer be restored.
- Deleting a secret deletes every version; the access log stays, and references to it fail the next deployment.

For linked secrets, rolling back to a version that recorded its value upstream **pins** the secret to that value; see [Rolling back a linked secret](/docs/secrets/providers/#rolling-back-a-linked-secret).

## Reveal

Only non-sensitive secrets can be revealed. Revealing needs `secrets.reveal` and a **recent re-authentication**: Falak asks for your password (and your authentication code with two-factor authentication) when you haven't confirmed it in the last 5 minutes. Every reveal is in the access log and the audit log, and more than 20 reveals by one user within 10 minutes fire `secrets.unusual_reveals`.

API tokens need the `secrets.reveal` ability **by name**; `*` is not enough.

## How secrets are protected

- Every value is encrypted with AES-256-GCM under the organization's **data key** and bound to its organization, secret and version: a value copied to another row no longer decrypts.
- Data keys are wrapped by the control plane's **key-encryption key (KEK)**, which is neither `APP_KEY` nor stored in the database or `.env`. See [Encryption keys](/docs/operations/security/#encryption-keys).
- The UI and the API return metadata only (name, scope, versions, last access), never values, unless revealed.

### On your servers

- **Classic sites** (PHP, Node, Bun, Deno, static): the site's `.env` lives on a tmpfs, `/run/falak/env/<site>.env` (mode 0440, the site's user and group); the release's `.env` is a symlink to it. After a reboot the agent reports the missing file and the control plane sends it again, so secrets are never written to persistent disk. Compose releases' `.env` works the same way.
- **Docker sites**: **Settings → Deploy → Secrets** chooses **Environment variables** (default) or **Files in /run/secrets** — each secret variable becomes a file such as `/run/secrets/DB_PASSWORD` on a tmpfs, so `docker inspect` never shows it. Applies from the next deploy.
- **Masking**: the values of secret variables are replaced with `••••` in deploy, hook, build and command output before anything leaves the server (also their base64 and URL-encoded forms), and the control plane masks the deployment log again. Secret variables are those that reference a secret, and those whose name looks like one (`*PASSWORD*`, `*SECRET*`, `*TOKEN*`, `*_KEY`, `DATABASE_URL`, …; not `VITE_`, `NEXT_PUBLIC_` and other browser variables).

Edit variables and secrets in Falak, not in `.env` on a server: the file is on a tmpfs, and Falak writes it again on every deploy and after a reboot.

## Permissions

| Action | Permission | Roles |
|---|---|---|
| See names, metadata, versions, access log and usage (never values) | `secrets.view` | owner, admin, developer, viewer |
| Create secrets, set values, roll back, disable versions, delete | `secrets.manage` | owner, admin, developer |
| Reveal non-sensitive values | `secrets.reveal` | owner, admin, developer |
| Add, edit, test and delete providers | `secrets.providers.manage` | owner, admin |

## Next steps
