Secret provisioning

Secret loading is unified behind a single SECRET_BACKEND toggle. This page explains the model; for the variable list, see Environment variables.

The backend toggle

SECRET_BACKEND is one of:

• env — secrets come only from the environment. SupaCloud never contacts a vault.
• openbao — secrets are hydrated from OpenBao at boot, with the environment as an override. A required secret missing from both vault and env is fatal at boot.

When SECRET_BACKEND is unset, SupaCloud auto-detects: it picks openbao if vault auth is present (a VAULT_TOKEN, or an AppRole id + secret), otherwise env.

One app-secret path

In OpenBao mode, application secrets live under a single KV v2 path, supacloud/app, keyed by environment-variable name. They are hydrated once at boot, filling fields that are still empty — for example the JWT secret, OIDC client secret, and bot tokens.

Where the key lives

The credential-encryption key is held in a write-once in-process holder, seeded at boot only when the key comes from the vault — so a vault-sourced key never enters the process environment. An operator-provided key stays in the environment where it was placed.

Caution

The encryption key is write-once by design: rotation is a redeploy. Never change a deployment’s credential-encryption key in place, or existing encrypted values will no longer decrypt.

Why

One toggle keeps small self-hosted deployments simple (env, no vault) while letting larger deployments centralize secrets in OpenBao without code changes — and moves the production validation guards after hydration, so a vault-provided secret satisfies them. This is the subject of ADR 0036.