Environment variable use
Use an environment variable or saved secret reference for provider credentials in a policy config. The gateway reads the value from its own process when it loads the file.
This page shows which fields take an environment variable, which also take a saved secret, and how to verify that the gateway can read them.
Set a local provider key
In the terminal that will start the gateway, set the key with your usual secret tool. For a local test:
export OPENAI_API_KEY="replace-with-your-provider-key"Refer to the variable by name in the provider target:
providers:
targets:
- id: openai-local
provider: openai
model: gpt-4o-mini
secret_key_ref:
env: OPENAI_API_KEYIn the same terminal, run verdictan gateway check --config policy-config.yaml. A missing key makes the target inactive when its secret reference has required: true. This check does not authenticate with the provider. Send a request to prove that the provider accepts the key.
A variable that you export in another terminal is not visible to the gateway. For a container, pass the variable into the container. For a service, set it in the service environment. See the quickstart in Docker and gateway service installation.
Select the credential source
| Source | Reference | Use it when |
|---|---|---|
| Gateway process environment | secret_key_ref: { env: OPENAI_API_KEY } | The gateway host owns the key. |
| Verdictan secret record | secret_key_ref: { store: OPENAI_API_KEY } | A connected agent has permission to read a saved key. |
A field that ends in _env | For example, url_env for Redis | The field itself names an environment variable. |
Where each form works
secret_key_ref object
| Field | Type | Description |
|---|---|---|
env | string | Name of an environment variable of the gateway process |
store | string | Name of a secret record created with verdictan secret create |
Set exactly one of env or store.
Surfaces that accept env and store
Only providers.targets[].secret_key_ref accepts both forms.
Surfaces that accept only env
These fields reject store:
moderation.secret_key_refpolicy.flagged-review.provider.secret_key_refpolicy.external-moderation.secret_key_refpolicy.tool-validation.semantic_validation.secret_key_refpolicy.tool-security.secret_key_refcallbacks[].secret_key_ref
With store on one of these, validation reports <field>.store is not supported in this config surface.
Literal *_env fields
These fields name a variable directly. They are special cases of their own sections, not a general rule.
| Field | Section | Variable holds |
|---|---|---|
public_key_env | callbacks[] with type: langfuse | The Langfuse public key |
secret_key_env | callbacks[] with type: langfuse | The Langfuse secret key |
url_env | distributed_rate_limit | The Redis or Valkey URL. Default VERDICTAN_LLM_CACHE_REDIS_URL. |
cloudflare_account_id_env | Cloudflare provider targets | The Cloudflare account ID |
snowflake_account_identifier_env | Snowflake Cortex provider targets | The Snowflake account identifier |
Callback credential fields
The gateway parses callback credentials, but no callback type delivers request events. See Observability configuration.
| Callback type | Credential fields |
|---|---|
langfuse | public_key_env, secret_key_env |
datadog | secret_key_ref.env |
helicone | secret_key_ref.env |
braintrust | secret_key_ref.env |
prometheus | None |
Execution environment maps
Execution targets take cli_env and adapter_env as maps of literal values. The gateway does not expand ${VAR} placeholders in them. If both maps have the same key, adapter_env wins.
Examples
Callback credentials
callbacks:
- type: langfuse
host: https://cloud.langfuse.com
public_key_env: VERDICTAN_LANGFUSE_PUBLIC_KEY
secret_key_env: VERDICTAN_LANGFUSE_SECRET_KEY
- type: datadog
secret_key_ref:
env: VERDICTAN_DATADOG_API_KEY
site: datadoghq.comExecution target environment
providers:
targets:
- id: browser-runner
provider: browser
adapter_command: /usr/local/bin/verdictan-browser-adapter
cli_env:
LOG_LEVEL: debug
adapter_env:
LOG_LEVEL: info
PLAYWRIGHT_BROWSERS_PATH: /opt/playwrightThe adapter receives LOG_LEVEL=info.
Hosted secret record for a connected gateway
A connected gateway reads store references through the hosted secret API. Create the record first. You need permission to manage secrets.
verdictan secret create \
--name OPENAI_API_KEY \
--env-var OPENAI_API_KEYThen refer to it by name:
providers:
targets:
- id: shared-openai
provider: openai
model: gpt-4o-mini
secret_key_ref:
store: OPENAI_API_KEYThe agent must have access to the secret before the gateway can read it. See Save a key and grant agent access.
Limits and failure behavior
- The gateway reads
envreferences from its own environment when it loads the file. A missing reference withrequired: truemakes the target unavailable. A check without that setting can report the target as active even when the provider will reject its credential. Send a live request aftergateway check. - A variable named
OPENAI_API_KEYdoes nothing on its own. A target must refer to it withsecret_key_ref.env. - A target without
secret_key_refcan parse and pass local checks. A provider that requires a key can still reject the request. Providers with their own authentication, such as Bedrock or Vertex AI, use their documented method. - The gateway token authenticates the gateway and lets it read its bound secrets. It is not a provider key.
- Change saved records with
verdictan secret updateand remove them withverdictan secret delete.
Next steps
- Provider configuration: the targets that refer to each credential.
- Manage secrets and credentials: create and rotate saved secrets.