> ## 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 API

> Create tenant secrets through a function version and name them in its spec, with the provider and errors behind them.

Alchemy has no separate secrets service. Secrets are created and referenced
through the function RPCs: `secret_values` on `CreateFunction` and
`CreateFunctionVersion` creates them, and `spec.secrets` names them. No RPC
lists, reads, rotates or deletes a secret, and no RPC returns a value. See
[Secrets](https://alchemy.getgalaxy.io/pages/concepts/secrets.md) for how values reach a function.

## Fields

| Field | Where | Type | Behavior |
| - | - | - | - |
| `secret_values` | `CreateFunctionRequest`, `CreateFunctionVersionRequest` | `map<string, string>` | Environment variable name to value. Each becomes a new tenant secret |
| `secrets` | `FunctionSpec` | `map<string, string>` | Environment variable name to the name of a secret this function's `secret_values` created |

## secret\_values

For each entry the server writes a secret named
`<function_id>.<suffix>.<VARIABLE>`, where the suffix is 8 random hex
characters shared by the version's values, and adds `VARIABLE` to the stored
`spec.secrets` under that name. Every version gets secrets of its own, so a new
version never changes what an older one reads. A variable named in both
`spec.secrets` and `secret_values` takes the new secret.

```json theme={null}
{
  "functionId": "<function-id>",
  "spec": {
    "image": "ghcr.io/galaxy-io/enrich-company:1.5.0",
    "protocol": "INVOCATION_PROTOCOL_EXEC",
    "contract": {"jsonSchema": {"input": {"type": "object"}, "output": {"type": "object"}}}
  },
  "secretValues": {"API_TOKEN": "s3cr3t"}
}
```

The returned version's `spec.secrets` then reads
`{"API_TOKEN": "<function-id>.1a2b3c4d.API_TOKEN"}`. After writing, the server
tells every host to drop its cached values for those names.

## spec.secrets

Each key must be an environment variable name (`^[A-Za-z_][A-Za-z0-9_]*$`).
Each value must be a secret name (`^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$`) that
an earlier `secret_values` created for the same function, such as when a
version's own spec is sent back as a new version. A function cannot name
another function's secret, and `CreateFunction` takes secrets only through
`secret_values`.

Values are never stored with the version. The host fetches them from the
server when it runs an invocation, and gets only the names the version it runs
lists in `spec.secrets`.

## Provider

The server stores secrets in the provider `SECRET_PROVIDER` selects, under the
ref `alchemy/<tenant>/<name>`.

| `SECRET_PROVIDER` | Store |
| - | - |
| unset or `datastore` | PostgreSQL, encrypted with the base64 AES key in `ENCRYPTION_KEY` (key id `ENCRYPTION_KEY_ID`, default `default`) |
| `aws-secrets-manager` | AWS Secrets Manager, with names rooted at `SECRETS_PREFIX` when set |
| `gcp-secret-manager` | GCP Secret Manager in `GCP_PROJECT_ID` and `GCP_REGION`, rooted at `SECRETS_PREFIX` when set |

With the datastore provider and no `ENCRYPTION_KEY`, the server starts with no
secret provider and logs a warning.

> [!WARNING]
>
> The existence check on `spec.secrets` reads the secrets table in PostgreSQL,
> which only the datastore provider writes. With `aws-secrets-manager` or
> `gcp-secret-manager`, `secret_values` works but a spec that names an existing
> secret is `not_found`.

See
[Configuration](https://alchemy.getgalaxy.io/pages/deployment/configuration.md).

## Errors

| Code | When |
| - | - |
| `failed_precondition` | `spec.secrets` or `secret_values` on a server with no secret provider |
| `invalid_argument` | A variable that is not an environment variable name, a value that is not a secret name, an empty value in `secret_values`, or a variable long enough to push the minted name past 128 characters |
| `permission_denied` | `spec.secrets` names a secret another function's `secret_values` created, or `spec.secrets` names any secret on `CreateFunction`, where `secret_values` is the only way in |
| `not_found` | `spec.secrets` names a secret the tenant does not have |
| `internal` | The provider failed to write |


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