Environment Variable Use

A policy config never contains a credential. It names the environment variable, or the saved secret, that holds it. 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:

Inside policy-config.yaml

providers:
  targets:
    - id: openai-local
      provider: openai
      model: gpt-4o-mini
      secret_key_ref:
        env: OPENAI_API_KEY

In the same terminal, run verdictan gateway check --config policy-config.yaml. It must report an active provider. A target whose key is missing does not become active. Then 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_ref
• policy.flagged-review.provider.secret_key_ref
• policy.external-moderation.secret_key_ref
• policy.tool-validation.semantic_validation.secret_key_ref
• policy.tool-security.secret_key_ref
• callbacks[].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

Inside policy-config.yaml

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.com

Execution target environment

Inside policy-config.yaml

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/playwright

The 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_KEY

Then refer to it by name:

Inside policy-config.yaml

providers:
  targets:
    - id: shared-openai
      provider: openai
      model: gpt-4o-mini
      secret_key_ref:
        store: OPENAI_API_KEY

The 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 env references from its own environment when it loads the file. If a required key is unset or empty, the target is not available. Run gateway check before you send traffic.
• A variable named OPENAI_API_KEY does nothing on its own. A target must refer to it with secret_key_ref.env.
• A target without secret_key_ref still parses, but a target that needs a key then stays out of routing. Providers with their own authentication, such as Bedrock or Vertex AI, use their documented method.
• The gateway runtime token authenticates the gateway and lets it read its bound secrets. It is not a provider key.
• Change saved records with verdictan secret update and remove them with verdictan secret delete.

Next steps

• Provider Configuration: the targets that refer to each credential.
• Manage Secrets and Credentials: create and rotate saved secrets.