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

# Secrets

> Tenant secrets are encrypted at rest, named in a version's spec and handed to the function's environment by the host at each invocation.

A secret is a value a function needs that must not live in its version, such as
an API key. Secrets belong to a tenant. A version names the ones it needs, and
the host fetches their values when it runs an invocation, so a value is never
stored with the version or baked into its snapshot.

## Where secrets are kept

The server keeps secrets through one provider, chosen by `SECRET_PROVIDER`:

| Provider | Storage |
| - | - |
| `datastore`, the default | PostgreSQL, encrypted with `ENCRYPTION_KEY`, a base64 AES key, under the key id `ENCRYPTION_KEY_ID` |
| `aws-secrets-manager` | AWS Secrets Manager, with the SDK's default credentials |
| `gcp-secret-manager` | GCP Secret Manager in `GCP_PROJECT_ID` and `GCP_REGION` |

The external providers name every secret under `SECRETS_PREFIX` when it is set.
With the default provider and no `ENCRYPTION_KEY`, the server starts with a
warning and has no secrets: a spec that uses them is `FAILED_PRECONDITION`.

## Naming secrets in a spec

`spec.secrets` maps an environment variable name to the name of a secret the
same function's `secret_values` created. Reuse the name from the function's
stored spec, which `GetFunctionVersion` returns:

```json theme={null}
{
  "secrets": {
    "CLEARBIT_KEY": "<function-id>.1a2b3c4d.CLEARBIT_KEY"
  }
}
```

| Part | Rule |
| - | - |
| Variable name | `^[A-Za-z_][A-Za-z0-9_]*$` |
| Secret name | `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$` |

Every secret a spec names must belong to the same function, so one function
never reads another's, or the version is refused with `PERMISSION_DENIED`. It
must also exist when the version is created, or the version is refused with
`NOT_FOUND`.

## Creating secrets with a version

`CreateFunction` and `CreateFunctionVersion` take `secret_values`, a map of
variable name to value. The server stores each value as a new secret and names
it in the version's `spec.secrets` for you. The name is the function id, a
random suffix shared by that version's values, and the variable, such as
`<function-id>.1a2b3c4d.CLEARBIT_KEY`.

Every version gets secrets of its own this way, so a new version never changes
what an older one reads. A value must not be empty.

> [!WARNING]
>
> `spec.env` is not for secrets. Its values are part of the version and visible
> wherever the version is, in the API and the web UI.

## How a value reaches the function

1. A host takes an invocation of a version that names secrets.
2. It asks a server for the values over the bus. The server answers only a host
   that has heartbeated recently, and only for the secrets that version names,
   in the version's own tenant.
3. The host keeps the values in memory, never on disk, for
   `SECRETS_REFRESH_INTERVAL`, 5 minutes by default, then asks again. A fetch
   that fails leaves the last value in use.
4. The host sends the values to the supervisor with the invocation, and the
   supervisor adds them to the function process's environment last, so they win
   over `spec.env` and the image's `Env`.

When `secret_values` writes new secrets, the server tells every host to drop
those names from its cache, so the next invocation reads the new value. The
refresh interval is the backstop when that message is missed.

A secret the host cannot get fails the attempt as a platform error, which
[retries](https://alchemy.getgalaxy.io/pages/concepts/invocations.md) like any other.

Secrets are part of an artifact by name only. The values never reach a
snapshot, since they are passed per invocation.


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