Skip to main content

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:

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

SourceReferenceUse it when
Gateway process environmentsecret_key_ref: { env: OPENAI_API_KEY }The gateway host owns the key.
Verdictan secret recordsecret_key_ref: { store: OPENAI_API_KEY }A connected agent has permission to read a saved key.
A field that ends in _envFor example, url_env for RedisThe field itself names an environment variable.

Where each form works​

secret_key_ref object​

FieldTypeDescription
envstringName of an environment variable of the gateway process
storestringName 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.

FieldSectionVariable holds
public_key_envcallbacks[] with type: langfuseThe Langfuse public key
secret_key_envcallbacks[] with type: langfuseThe Langfuse secret key
url_envdistributed_rate_limitThe Redis or Valkey URL. Default VERDICTAN_LLM_CACHE_REDIS_URL.
cloudflare_account_id_envCloudflare provider targetsThe Cloudflare account ID
snowflake_account_identifier_envSnowflake Cortex provider targetsThe Snowflake account identifier

Callback credential fields​

The gateway parses callback credentials, but no callback type delivers request events. See Observability configuration.

Callback typeCredential fields
langfusepublic_key_env, secret_key_env
datadogsecret_key_ref.env
heliconesecret_key_ref.env
braintrustsecret_key_ref.env
prometheusNone

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. A missing reference with required: true makes 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 after gateway check.
  • 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 can 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 update and remove them with verdictan secret delete.

Next steps​