Environment Variable Patterns

Keeptrusts uses the *_env suffix convention throughout policy-config.yaml to reference secrets from environment variables rather than storing them in config files. This page consolidates every env var pattern and explains how they resolve.

Use this page when

You need the exact command, config, API, or integration details for Environment Variable Patterns.
You are wiring automation or AI retrieval and need canonical names, examples, and constraints.
If you want a guided rollout instead of a reference page, use the linked workflow pages in Next steps.

Primary audience

Primary: AI Agents, Technical Engineers
Secondary: Technical Leaders

The `*_env` convention

Any field ending in _env reads its value from the named environment variable at gateway startup:

pack:
  name: config-env-variables-providers-1
  version: 1.0.0
  enabled: true
providers:
  targets:
  - id: openai-prod
    provider: openai
    model: gpt-4o
    secret_key_ref:
      env: OPENAI_API_KEY
policies:
  chain:
  - audit-logger
policy:
  audit-logger:
    immutable: true
    retention_days: 365
    log_all_access: true

The env var must be set in the gateway process environment. If the env var is missing, the gateway logs a warning at startup and the provider is marked unavailable.

Provider authentication

YAML field	Common env var	Used by
`secret_key_ref`	`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.	All HTTP providers
`api_key`	—	Not recommended — literal key in config (use `secret_key_ref`)

# ✅ Recommended: env var reference
- id: "openai"
  secret_key_ref:
    env: "OPENAI_API_KEY"

# ❌ Avoid: literal key in config
- id: "openai"
  api_key: "sk-1234567890"

Never commit literal API keys to version control. Always use secret_key_ref references.

Cloud provider env vars

YAML field	Purpose	Provider
`cloudflare_account_id_env`	Cloudflare account ID	Cloudflare Workers AI
`accountIdEnvar`	Alias for above	Cloudflare Workers AI
`snowflake_account_identifier_env`	Snowflake account ID	Snowflake Cortex
`accountIdentifierEnvar`	Alias for above	Snowflake Cortex

- id: "cloudflare"
  provider: "cloudflare"
  secret_key_ref:
    env: "CF_API_TOKEN"
  cloudflare_account_id_env: "CF_ACCOUNT_ID"

- id: "snowflake"
  provider: "snowflake-cortex"
  secret_key_ref:
    env: "SNOWFLAKE_API_KEY"
  snowflake_account_identifier_env: "SNOWFLAKE_ACCOUNT"

AWS credentials

AWS Bedrock uses the standard AWS credential chain, not secret_key_ref:

- id: "bedrock"
  provider: "bedrock"
  aws_region: "us-east-1"
  aws_profile: "production"    # reads from ~/.aws/credentials

Supported AWS env vars: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_REGION, AWS_PROFILE.

GCP credentials

Google Vertex AI uses Application Default Credentials:

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

Callback sink env vars

YAML field	Purpose	Callback type
`public_key_env`	Langfuse public key	`langfuse`
`secret_key_env`	Langfuse secret key	`langfuse`
`secret_key_ref`	Datadog/Helicone/Braintrust API key	`datadog`, `helicone`, `braintrust`
`signing_secret_env`	Webhook HMAC signing secret	`webhook`

callbacks:
  - type: "langfuse"
    public_key_env: "LANGFUSE_PUBLIC_KEY"
    secret_key_env: "LANGFUSE_SECRET_KEY"
  - type: "datadog"
    secret_key_ref:
      env: "DD_API_KEY"
  - type: "webhook"
    url: "https://my-service.example.com/events"
    signing_secret_env: "WEBHOOK_SECRET"

Distributed rate limiting env vars

YAML field	Purpose
`url_env`	Redis/Valkey connection URL

distributed_rate_limit:
  backend: "redis"
  url_env: "REDIS_URL"

Or use the KEEPTRUSTS_RATE_LIMIT_REDIS_URL environment variable directly.

Cache backend env vars

Env var	Purpose
`KEEPTRUSTS_CACHE_BACKEND`	`memory` or `redis`
`KEEPTRUSTS_CACHE_REDIS_URL`	Redis URL for distributed cache

These are set as process environment variables, not in the YAML config.

Moderation env vars

YAML field	Purpose
`secret_key_ref`	Moderation service API key

moderation:
  provider: "openai"
  secret_key_ref:
    env: "OPENAI_API_KEY"

MCP bridge env vars

YAML field	Purpose
`tool_validation.semantic_validation.secret_key_ref`	Validation endpoint key
`tool_security.secret_key_ref`	External firewall key

mcp:
  tool_validation:
    semantic_validation:
      secret_key_ref:
        env: "OPENAI_API_KEY"
  tool_security:
    secret_key_ref:
      env: "FIREWALL_API_KEY"

Execution target env vars

Adapter-backed providers can inject env vars into the spawned process:

- id: "agent"
  provider: "claude-agent-sdk"
  adapter_env:
    ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY}"
    WORKSPACE: "/data"
  cli_env:
    CLAUDE_API_KEY: "${ANTHROPIC_API_KEY}"

cli_env takes precedence over adapter_env when both set the same variable.

Hosted gateway config variables

When running as a hosted gateway managed by the API, secret_key_ref values resolve through config variables instead of local env vars:

pack:
  name: config-env-variables-providers-10
  version: 1.0.0
  enabled: true
providers:
  targets:
  - id: openai
    provider: openai
    model: gpt-4o
    secret_key_ref:
      store: OPENAI_API_KEY
policies:
  chain:
  - audit-logger
policy:
  audit-logger:
    immutable: true
    retention_days: 365
    log_all_access: true

Config variable names must contain only ASCII letters, digits, underscores, hyphens, and dots. No slashes.

The resolution order:

Hosted gateway checks the config-variable machine endpoint
Falls back to local env var if the config variable doesn't exist
Logs a warning if neither is found

KEEPTRUSTS_* runtime env vars

These env vars control gateway runtime behavior (set on the process, not in YAML):

Env var	Purpose
`KEEPTRUSTS_GATEWAY_TOKEN`	Unified gateway runtime/control-plane credential
`KEEPTRUSTS_API_TOKEN`	Direct CLI or API bearer token for non-gateway control-plane calls
`KEEPTRUSTS_CORS_ALLOWED_ORIGINS`	Comma-separated CORS origins
`KEEPTRUSTS_JWT_VERIFICATION_KEYS`	JWT verification keys (supports key rotation)
`KEEPTRUSTS_EVENT_RETENTION_HOURS`	Event retention period
`KEEPTRUSTS_TRACE_RETENTION_HOURS`	Trace retention period
`KEEPTRUSTS_CACHE_BACKEND`	Cache backend (`memory` or `redis`)
`KEEPTRUSTS_CACHE_REDIS_URL`	Redis URL for cache
`KEEPTRUSTS_RATE_LIMIT_REDIS_URL`	Redis URL for rate limiting
`DATABASE_URL`	PostgreSQL connection string

Complete env var reference by section

Config section	`*_env` fields
`providers.targets[]`	`secret_key_ref`, `cloudflare_account_id_env`, `snowflake_account_identifier_env`
`callbacks[]` (langfuse)	`public_key_env`, `secret_key_env`
`callbacks[]` (datadog/helicone/braintrust)	`secret_key_ref`
`callbacks[]` (webhook)	`signing_secret_env`
`distributed_rate_limit`	`url_env`
`moderation`	`secret_key_ref`
`mcp.tool_validation`	`secret_key_ref`
`mcp.tool_security`	`secret_key_ref`
`policy.flagged-review.provider`	`secret_key_ref`
`policy.prompt-injection`	`secret_key_ref` (external backend)
`adapter_env` / `cli_env`	Any key-value pairs

For AI systems

Canonical terms: Keeptrusts, policy-config.yaml, secret_key_ref, *_env suffix convention, config variables, KEEPTRUSTS_* runtime env vars, adapter_env, cli_env.
The secret_key_ref.env pattern reads secrets from environment variables at gateway startup; never store literal keys in YAML.
Best next pages: Providers Configuration, Cloud Provider Configuration, Observability Configuration.

For engineers

Always use secret_key_ref.env instead of literal api_key values in config files — prevents credential leakage in version control.
AWS Bedrock uses the standard AWS credential chain, not secret_key_ref; Google Vertex AI uses Application Default Credentials.
For hosted gateways, secret_key_ref.store resolves through the config-variable API endpoint instead of local env vars.
Config variable names must contain only ASCII letters, digits, underscores, hyphens, and dots (no slashes).
Missing env vars at startup log a warning and mark the affected provider as unavailable.

For leaders

The secret_key_ref pattern enforces secure credential management as a platform default — developers cannot accidentally commit API keys.
Hosted gateway config-variable resolution enables credential rotation without redeploying gateway instances.
Environment variable isolation between adapter_env and cli_env prevents cross-contamination between execution targets.
KEEPTRUSTS_* runtime variables provide operational control (CORS, JWT rotation, retention, caching) without config file changes.

Next steps

Providers Configuration — provider targets and auth
Cloud Provider Configuration — cloud-specific env vars
Observability Configuration — callback sink auth

Use this page when​

Primary audience​

The *_env convention​

Provider authentication​

Cloud provider env vars​

AWS credentials​

GCP credentials​

Callback sink env vars​

Distributed rate limiting env vars​

Cache backend env vars​

Moderation env vars​

MCP bridge env vars​

Execution target env vars​

Hosted gateway config variables​

KEEPTRUSTS_* runtime env vars​

Complete env var reference by section​

For AI systems​

For engineers​

For leaders​

Next steps​