Skip to main content

Env-Backed Secrets

Every sensitive field on every credential type in Zerq supports environment variable backing. Instead of storing the secret value in the database, you reference a container environment variable that is resolved at runtime.

How it works​

For each sensitive field, the credential form shows two sub-fields:

  • Use Env Var toggle — when enabled, the value input is replaced by an env var name input
  • Env Var Name — the name of the container environment variable to read at runtime

When Zerq needs to make an outbound request using this credential, it reads the environment variable from the gateway process's environment. If the variable is not set, the request fails with an internal error.

Which fields support env-var backing​

Credential TypeFields that support env-var backing
Basic Authpassword
API Keyapi_key
OAuth2 Client Credentialsclient_secret
mTLS Client Certificateclient_cert_pem, client_key_pem, ca_cert_pem
MongoDBuri (full connection string)
PostgreSQLFull DSN / connection string
SQL ServerFull connection string
OracleConnection string / DSN
Redispassword
SMTPpassword
SendGridapi_key
Kafkasasl_password, ssl_key_pem, ssl_cert_pem, ssl_ca_pem

Non-sensitive fields (hostname, port, username, database name) are always stored directly and do not support env-var mode.

Configuration walkthrough​

Example: API Key credential backed by an environment variable

  1. Create or edit an API Key credential.
  2. For the api_key field, enable the Use Env Var toggle.
  3. Enter the environment variable name: PAYMENTS_API_KEY
  4. Save the credential.

At runtime, the gateway reads PAYMENTS_API_KEY from the container environment and uses that value as the API key.

Set the environment variable on the gateway container:

# Docker Compose (docker-compose.yml or .env file)
PAYMENTS_API_KEY=sk_live_xxxxxxxxxxxxxxxx

# Kubernetes (Secret → envFrom or env[].valueFrom.secretKeyRef)
kubectl create secret generic gateway-secrets \
  --from-literal=PAYMENTS_API_KEY=sk_live_xxxxxxxxxxxxxxxx

Naming conventions​

Keep env var names stable and consistent across environments:

  • PAYMENTS_API_KEY — not PROD_PAYMENTS_KEY (environment should not be encoded in the name)
  • CRM_CLIENT_SECRET — service-specific prefix
  • KAFKA_SASL_PASSWORD — component-specific prefix

The same credential configuration works in dev, staging, and production — only the injected values differ.

Rotation​

To rotate an env-var-backed secret:

  1. Update the environment variable value on the gateway container (e.g., update the Kubernetes secret or .env file)
  2. Restart or re-deploy the gateway container to pick up the new value
  3. Verify with a test request — no changes needed in the Zerq credential configuration

Failure signatures​

ErrorLikely cause
502 Bad Gateway (upstream auth failure)Env var not set, wrong value, or gateway not restarted after rotation
Gateway internal errorEnv var name is set on the credential but the variable doesn't exist in the container environment
401 from upstreamSecret value is wrong — check that the env var value matches what the upstream API expects